Skip to content

Installation Guide

Get up and running in under 5 minutes. This guide includes setup for 24 MCP clients including Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, and Windsurf, and more.

Prerequisites: You'll need an API key from app.maguyva.ai and a connected GitHub repository.

Environment Setup#

First, set your API key in an environment variable. Omit repository when your MCP client supplies a request default or the key can access exactly one repository; otherwise pass it explicitly.

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

Replace mgv_xxxx with your actual API key from app.maguyva.ai.

Client Configuration#

Choose your MCP client below for specific setup instructions.

Compatibility note: Maguyva uses standard MCP. Any client with MCP support can connect to the same server, even if we have not written a first-party setup guide for it yet.

Claude Code

Install the Maguyva plugin from the Claude Code marketplace:

Add the Maguyva marketplace, then install the plugin (run each command inside Claude Code):

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

Installs for your user account. For a team, add --scope project to both commands to commit the plugin to the repository's .claude/settings.json so teammates get it automatically.

The plugin authenticates via the MAGUYVA_API_KEY environment variable. Set it in your shell:

export MAGUYVA_API_KEY=mgv_xxxx

Per-project direnv (.envrc) is recommended — keys are repository-scoped, so a per-project value matches each project's access. A global shell export works if one key covers all your work.

Manual (.mcp.json) — advanced
.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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

Claude Code MCP docs →

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

Add to your Claude Desktop configuration file:

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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

Claude Desktop only supports remote servers as OAuth "connectors" via Settings, not as a header-authenticated entry in claude_desktop_config.json, so this uses the mcp-remote bridge (requires Node.js / npx).

Claude Desktop MCP docs →

Cursor

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

Add to .cursor/mcp.json in your project root:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Cursor MCP docs →

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project (or user settings):

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

VS Code / GitHub Copilot MCP docs →

Windsurf

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

Add to your Windsurf MCP configuration:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Windsurf MCP docs →

Codex

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

Add to your Codex CLI config (~/.codex/config.toml):

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

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Codex MCP docs →

GitHub Copilot CLI

Add to .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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

GitHub Copilot CLI MCP docs →

Gemini CLI

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

Add to your Gemini CLI settings (~/.gemini/settings.json):

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Gemini CLI MCP docs →

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

Add to your Cline MCP settings:

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
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

Cline MCP docs →

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

Add to your Roo Code MCP settings:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Roo Code MCP docs →

Goose

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

Add to your Goose config:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

Goose MCP docs →

LM Studio

LM Studio supports MCP servers via its Agent configuration. Add a new MCP server in Settings → Agent → MCP Servers using the standard mcpServers JSON format. LM Studio connects to MCP servers over stdio. See docs →

Continue

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

Add to your Continue config (~/.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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

Continue MCP docs →

Amazon Q Developer

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

Add to your Amazon Q MCP config:

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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

Amazon Q Developer MCP docs →

PyCharm

Add to .ai/mcp/mcp.json in your project root, or paste in 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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

PyCharm MCP docs →

Zed

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

Add to your Zed settings (~/.config/zed/settings.json):

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Zed MCP docs →

Trae

Add to .trae/mcp.json in your project root:

.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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

Trae MCP docs →

OpenCode

Add to opencode.json in your project root:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

OpenCode MCP docs →

BoltAI

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

Add to your BoltAI MCP configuration:

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"
      }
    }
  }
}

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

BoltAI MCP docs →

LibreChat

Add to your LibreChat configuration:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

This client does not yet support a remote MCP server with a custom auth header, so it connects through the mcp-remote bridge (requires Node.js / npx). Maguyva runs entirely remotely — only the bridge runs locally.

LibreChat MCP docs →

Antigravity

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

Add to your Antigravity MCP configuration:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Antigravity MCP docs →

Claude Cowork

Claude Cowork uses the same MCP format as other Anthropic clients:

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

Replace mgv_xxxx with your API key from app.maguyva.ai.

Claude Cowork MCP docs →

ChatGPT

ChatGPT supports remote MCP servers on Business, Enterprise, and Edu plans via Settings → Apps → Create. A remote HTTPS endpoint is required — ChatGPT does not support local stdio servers. See OpenAI’s MCP guide for setup. See docs →

Warp

Warp supports MCP servers in Agent Mode. Configuration is managed through the Warp UI (Settings → Agent Mode → MCP Servers) and synced via Warp Drive. Paste the standard mcpServers JSON when adding a server. See docs →

Maguyva uses standard MCP. Any client that supports the protocol can connect — even if there is no first-party guide above.24 clients documented, more added regularly.

Validate Your Setup#

After connecting, try asking your agent a few questions:

  • "What repositories do I have connected?" — verifies the connection is working
  • "How is authentication handled in this codebase?" — tests semantic search
  • "Find all functions that call the database" — tests dependency search
  • "What does the UserService class depend on?" — tests symbol lookup

You should see results with file paths and line numbers from your connected repository. If not, check the troubleshooting section below.

Repository Format#

When specifying repositories:

  • With branch: "owner/repo:branch" (e.g., "owner/repository:develop")
  • Default branch: "owner/repo"

Tip: Use repository_context(action="info", repository="...") to verify repository resolution. The v3 server is stateless, so repository overrides apply to one call only.

Troubleshooting#

API Key Issues#

  • Verify your key starts with mgv_ prefix
  • Check the key is correctly set in your environment
  • Ensure the key hasn't expired

Repository Not Found#

  • Verify the repository is connected in app.maguyva.ai
  • Check the owner/repo format is correct
  • Ensure you have access to the repository

MCP Connection Issues#

  • Verify npx is available in your PATH
  • Check that your API token is valid and not expired
  • Test connectivity to https://maguyva.tools/mcp
  • Check your client's MCP configuration syntax

Next Steps#