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. The repository is set at runtime via repository_context(action="set").

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 MCP server via Claude Code CLI:

export MAGUYVA_API_KEY=mgv_xxxx
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header "Authorization: Bearer ${MAGUYVA_API_KEY}"

Or add directly to .mcp.json in your project root (committed to git):

.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 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": {
      "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.

Cursor MCP docs →

VS Code / GitHub Copilot

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

.vscode/mcp.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.

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": {
      "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.

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]
command = "npx"
args = [ "-y", "mcp-remote", "https://maguyva.tools/mcp", "--header", "Authorization: Bearer ${MAGUYVA_API_KEY}" ]

[mcp_servers.maguyva.env]
MAGUYVA_API_KEY = "mgv_xxxx"

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": {
      "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.

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.

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": {
      "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.

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.

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.

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.

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.

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": {
      "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.

For remote MCP servers, Zed may require mcp-remote as a bridge.

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.

Trae MCP docs →

OpenCode

Add to opencode.json in your project root:

opencode.json 
{
  "mcp": {
    "maguyva": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "enabled": true,
      "environment": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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.

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.

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": {
      "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.

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: Set session context with repository_context(action="set", repository="...") to avoid repeating it in every call where your MCP client allows session defaults.

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 #