How do I troubleshoot problemy z kluczem api?

Sprawdź, czy klucz zaczyna się od przedrostka mgv_ Sprawdź, czy klucz jest poprawnie ustawiony w twoim środowisku Upewnij się, że klucz nie wygasł

How do I troubleshoot nie znaleziono repozytorium?

Sprawdź, czy repozytorium jest połączone w app.maguyva.ai Sprawdź, czy format owner/repo jest poprawny Upewnij się, że masz dostęp do repozytorium

How do I troubleshoot problemy z połączeniem mcp?

Sprawdź, czy npx jest dostępne w twojej ścieżce PATH Sprawdź, czy twój token API jest ważny i nie wygasł Przetestuj połączenie z https://maguyva.tools/mcp Sprawdź składnię konfiguracji MCP twojego klienta

Jak sprawdzić, czy konfiguracja Maguyva MCP działa poprawnie?

Po połączeniu zadaj swojemu agentowi pytania, które testują różne tryby wyszukiwania: "Jakie repozytoria mam połączone?" (sprawdza, czy połączenie działa); "Jak obsługiwane jest uwierzytelnianie w tym kodzie?" (testuje wyszukiwanie semantyczne); "Znajdź wszystkie funkcje, które wywołują bazę danych" (testuje wyszukiwanie zależności); "Od czego zależy klasa UserService?" (testuje wyszukiwanie symboli). Powinieneś zobaczyć wyniki ze ścieżkami plików i numerami linii z połączonego repozytorium.

Jak określić repozytorium w zapytaniach Maguyva MCP?

Pomiń repozytorium, gdy twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium. W przeciwnym razie użyj "owner/repo" dla domyślnej gałęzi (np. "owner/repository") lub "owner/repo:branch" dla konkretnej gałęzi (np. "owner/repository:develop").

Przewodnik instalacji

Uruchom wszystko w mniej niż 5 minut. Ten przewodnik obejmuje konfigurację dla 24 klientów MCP, w tym Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot i Windsurf i innych.

Wymagania wstępne: Potrzebujesz klucza API z app.maguyva.ai oraz połączonego repozytorium GitHub.

Konfiguracja środowiska#

Najpierw ustaw klucz API w zmiennej środowiskowej. Pomiń repository, gdy twój klient MCP dostarcza domyślne ustawienie dla żądania lub gdy klucz ma dostęp dokładnie do jednego repozytorium; w przeciwnym razie przekaż je jawnie.

macOS/Linux (Bash/Zsh)#

# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)#

# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

Zastąp mgv_xxxx swoim rzeczywistym kluczem API z app.maguyva.ai.

Konfiguracja klienta#

Wybierz poniżej swojego klienta MCP, aby zobaczyć szczegółowe instrukcje konfiguracji.

Uwaga dotycząca kompatybilności: Maguyva wykorzystuje standardowy MCP. Każdy klient obsługujący MCP może połączyć się z tym samym serwerem, nawet jeśli nie napisaliśmy jeszcze dla niego oficjalnego przewodnika konfiguracji.

Claude Code

Zainstaluj plugin Maguyva z marketplace Claude Code:

Dodaj marketplace Maguyva, a następnie zainstaluj plugin (uruchom każdą komendę wewnątrz Claude Code):

/plugin marketplace add maguyva/claude-code-plugin
/plugin install maguyva@maguyva

Instaluje dla Twojego konta użytkownika. Dla zespołu dodaj --scope project do obu komend, aby zatwierdzić plugin w pliku .claude/settings.json repozytorium, dzięki czemu współpracownicy otrzymają go automatycznie.

Plugin uwierzytelnia się za pomocą zmiennej środowiskowej MAGUYVA_API_KEY. Ustaw ją w swojej powłoce:

export MAGUYVA_API_KEY=mgv_xxxx

Zalecane jest użycie direnv per projekt (.envrc) — klucze są przypisane do repozytorium, więc wartość per projekt odpowiada dostępowi każdego projektu. Globalny eksport w powłoce sprawdzi się, jeśli jeden klucz obejmuje całą Twoją pracę.

Ręczna (.mcp.json) — zaawansowane

.mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Claude Code →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Dodaj do pliku konfiguracyjnego Claude Desktop:

claude_desktop_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Claude Desktop obsługuje zdalne serwery wyłącznie jako łączniki OAuth („connectors") w Settings, a nie jako wpis uwierzytelniany nagłówkiem w claude_desktop_config.json, dlatego korzysta z mostka mcp-remote (wymaga Node.js / npx).

Dokumentacja MCP Claude Desktop →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

Dodaj do .cursor/mcp.json w katalogu głównym swojego projektu:

.cursor/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Cursor →

VS Code / GitHub Copilot

Dodaj do .vscode/mcp.json w swoim projekcie (lub w ustawieniach użytkownika):

.vscode/mcp.json

{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP VS Code / GitHub Copilot →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

Dodaj do konfiguracji MCP w Windsurf:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Windsurf →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

Dodaj do konfiguracji Codex CLI (~/.codex/config.toml):

.codex/config.toml

[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Codex →

GitHub Copilot CLI

Dodaj do .copilot/mcp-config.json:

.copilot/mcp-config.json

{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP GitHub Copilot CLI →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

Dodaj do ustawień Gemini CLI (~/.gemini/settings.json):

settings.json

{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Gemini CLI →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Dodaj do ustawień MCP w Cline:

cline_mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Ten klient nie obsługuje jeszcze zdalnego serwera MCP z niestandardowym nagłówkiem uwierzytelniania, więc łączy się przez mostek mcp-remote (wymaga Node.js / npx). Maguyva działa całkowicie zdalnie — lokalnie działa tylko mostek.

Dokumentacja MCP Cline →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

Dodaj do ustawień MCP w Roo Code:

mcp_settings.json

{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Roo Code →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %AppData%\goose\config.yaml
Linux: ~/.config/goose/config.yaml

Dodaj do konfiguracji Goose:

config.yaml

extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Goose →

LM Studio

LM Studio obsługuje serwery MCP poprzez konfigurację Agenta. Dodaj nowy serwer MCP w Settings → Agent → MCP Servers, korzystając ze standardowego formatu JSON mcpServers. LM Studio łączy się z serwerami MCP przez stdio. Zobacz dokumentację →

Continue

macOS: ~/.continue/config.json
Windows: %UserProfile%\.continue\config.json
Linux: ~/.continue/config.json

Dodaj do konfiguracji Continue (~/.continue/config.json):

config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Continue →

Amazon Q Developer

macOS: ~/.aws/amazonq/mcp.json
Windows: %UserProfile%\.aws\amazonq\mcp.json
Linux: ~/.aws/amazonq/mcp.json

Dodaj do konfiguracji MCP w Amazon Q:

mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Amazon Q Developer →

PyCharm

Dodaj do .ai/mcp/mcp.json w katalogu głównym projektu albo wklej w Settings > Tools > AI Assistant > MCP:

.ai/mcp/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP PyCharm →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

Dodaj do ustawień Zed (~/.config/zed/settings.json):

settings.json

{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Zed →

Trae

Dodaj do .trae/mcp.json w katalogu głównym swojego projektu:

.trae/mcp.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Trae →

OpenCode

Dodaj do opencode.json w katalogu głównym swojego projektu:

opencode.json

{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP OpenCode →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

Dodaj do konfiguracji MCP w BoltAI:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP BoltAI →

LibreChat

Dodaj do konfiguracji LibreChat:

librechat.yaml

mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP LibreChat →

Antigravity

macOS: ~/.gemini/antigravity/mcp_config.json
Windows: %UserProfile%\.gemini\antigravity\mcp_config.json
Linux: ~/.gemini/antigravity/mcp_config.json

Dodaj do konfiguracji MCP w Antigravity:

mcp_config.json

{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Antigravity →

Claude Cowork

Claude Cowork korzysta z tego samego formatu MCP co inni klienci Anthropic:

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

Zastąp mgv_xxxx swoim kluczem API z app.maguyva.ai.

Dokumentacja MCP Claude Cowork →

ChatGPT

ChatGPT obsługuje zdalne serwery MCP w planach Business, Enterprise i Edu poprzez Settings → Apps → Create. Wymagany jest zdalny endpoint HTTPS — ChatGPT nie obsługuje lokalnych serwerów stdio. Instrukcje konfiguracji znajdziesz w przewodniku MCP od OpenAI. Zobacz dokumentację →

Warp

Warp obsługuje serwery MCP w trybie Agent Mode. Konfiguracja jest zarządzana przez interfejs Warp (Settings → Agent Mode → MCP Servers) i synchronizowana przez Warp Drive. Podczas dodawania serwera wklej standardowy JSON mcpServers. Zobacz dokumentację →

Maguyva korzysta ze standardowego MCP. Może się połączyć każdy klient obsługujący ten protokół — nawet jeśli powyżej nie ma dla niego oficjalnego przewodnika. Udokumentowano 24 klientów, a kolejne są regularnie dodawane.

Zweryfikuj swoją konfigurację#

Po połączeniu spróbuj zadać swojemu agentowi kilka pytań:

"Jakie repozytoria mam połączone?" — sprawdza, czy połączenie działa
"Jak obsługiwane jest uwierzytelnianie w tym kodzie?" — testuje wyszukiwanie semantyczne
"Znajdź wszystkie funkcje, które wywołują bazę danych" — testuje wyszukiwanie zależności
"Od czego zależy klasa UserService?" — testuje wyszukiwanie symboli

Powinieneś zobaczyć wyniki ze ścieżkami plików i numerami linii z połączonego repozytorium. Jeśli nie, sprawdź troubleshooting section poniżej.

Format repozytorium#

Przy określaniu repozytoriów:

Z gałęzią: "owner/repo:branch" (e.g., "owner/repository:develop")
Domyślna gałąź: "owner/repo"

Wskazówka: Użyj repository_context(action="info", repository="..."), aby zweryfikować rozwiązanie repozytorium. Serwer v3 nie przechowuje stanu, więc nadpisania repozytorium obowiązują tylko dla jednego wywołania.

Rozwiązywanie problemów#

Problemy z kluczem API#

Sprawdź, czy klucz zaczyna się od przedrostka mgv_
Sprawdź, czy klucz jest poprawnie ustawiony w twoim środowisku
Upewnij się, że klucz nie wygasł

Nie znaleziono repozytorium#

Sprawdź, czy repozytorium jest połączone w app.maguyva.ai
Sprawdź, czy format owner/repo jest poprawny
Upewnij się, że masz dostęp do repozytorium

Problemy z połączeniem MCP#

Sprawdź, czy npx jest dostępne w twojej ścieżce PATH
Sprawdź, czy twój token API jest ważny i nie wygasł
Przetestuj połączenie z https://maguyva.tools/mcp
Sprawdź składnię konfiguracji MCP twojego klienta

Kolejne kroki#

Dokumentacja API MCP - Pełna dokumentacja API
Jak to działa - Zrozum optymalizację kontekstu
Rozwiązywanie problemów - Napraw problemy z konfiguracją i połączeniem