Skip to content

Installation Guide

Get up and running in under 5 minutes. This guide includes setup for 23 MCP clients including Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot, and Devin Desktop (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/agent-plugins
/plugin install maguyva@maguyva

/plugin install opens the plugin's details, where you choose the install scope: just you (user), everyone working in this repository (project), or just you in this repository (local). These in-session commands take no --scope flag.

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.

For a team, you can instead run the shell form of both commands from the repository root, outside Claude Code:

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

Project scope records the plugin in the repository's .claude/settings.json, which you commit. That turns the plugin on for teammates but does not download it, so each teammate runs the install command once.

Manual (.mcp.json) — advanced
claude mcp add 
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'
.mcp.json 
{
  "mcpServers": {
    "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.

What Maguyva adds to Claude Code →

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",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

claude_desktop_config.json starts local servers only, so this setup uses the @maguyva/mcp bridge (requires Node.js / npx). Claude Desktop can also reach Maguyva as a custom connector (Customize → Connectors) with an authorization request header, but request headers are in beta for a limited set of organizations.

What Maguyva adds to Claude Desktop →

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 ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

What Maguyva adds to Cursor →

Cursor MCP docs →

VS Code / GitHub Copilot

Add to .vscode/mcp.json in your project, or to your profile’s mcp.json (run MCP: Open User Configuration):

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

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

This is the VS Code format (servers key). VS Code resolves the MAGUYVA_API_KEY reference from the environment it starts in. Its Add Server flow now prefers the portable .mcp.json (mcpServers key) that GitHub Copilot CLI also reads; that file does not support VS Code input variables or environment files.

What Maguyva adds to VS Code / GitHub Copilot →

VS Code / GitHub Copilot MCP docs →

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

Windsurf is now Devin Desktop. Add to its MCP configuration file:

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

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

Devin Local, the default agent, reads this file from version 3.6; earlier versions kept servers in the main config file and move them here on startup. The legacy Cascade agent, which new conversations do not start on, reads the same file. Devin Desktop resolves the MAGUYVA_API_KEY reference from the environment it starts in.

What Maguyva adds to Devin Desktop (Windsurf) →

Devin Desktop (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"
bearer_token_env_var = "MAGUYVA_API_KEY"

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

What Maguyva adds to Codex →

Codex MCP docs →

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
copilot mcp add 
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

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

What Maguyva adds to GitHub Copilot CLI →

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

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

What Maguyva adds to Gemini CLI →

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": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

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

What Maguyva adds to Cline →

Cline MCP docs →

Goose

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

Add to your Goose config:

config.yaml 
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

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

What Maguyva adds to Goose →

Goose MCP docs →

LM Studio

In LM Studio, open the Program tab in the right-hand sidebar, choose Install → Edit mcp.json, and add:

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

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

LM Studio MCP docs →

Continue

Save as .continue/mcpServers/maguyva.yaml in your workspace (or add the mcpServers entry to ~/.continue/config.yaml), then set MAGUYVA_API_KEY in ~/.continue/.env:

.continue/mcpServers/maguyva.yaml 
name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

Continue uses MCP servers in agent mode only. It looks up the secret in ~/.continue/.env, then the workspace .continue/.env and .env, then the process environment.

What Maguyva adds to Continue →

Continue MCP docs →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

Add to your Kiro CLI MCP config (~/.kiro/settings/mcp.json, or .kiro/settings/mcp.json in a project):

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

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

Kiro CLI replaced Amazon Q Developer CLI. Installing it copies your servers from ~/.aws/amazonq/mcp.json to ~/.kiro/settings/mcp.json once, and a project's .kiro/settings/mcp.json takes precedence over the user file.

Kiro CLI (Amazon Q Developer CLI) MCP docs →

PyCharm

Paste in Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add, as a JSON configuration: 

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

This setup uses the @maguyva/mcp bridge (requires Node.js / npx). A native remote configuration for this client has not been verified in this guide; this does not mean the client lacks native remote support. 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 mgv_xxxx"
      }
    }
  }
}

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

What Maguyva adds to Zed →

Zed MCP docs →

Trae

Turn on Enable Project MCP in Settings → MCP, then add to .trae/mcp.json in your project root:

.trae/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer 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": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

What Maguyva adds to OpenCode →

OpenCode MCP docs →

BoltAI

macOS: ~/.boltai/mcp.json

Add to your BoltAI MCP configuration:

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

This setup uses the @maguyva/mcp bridge (requires Node.js / npx). A native remote configuration for this client has not been verified in this guide; this does not mean the client lacks native remote support. Maguyva runs entirely remotely — only the bridge runs locally.

BoltAI MCP docs →

LibreChat

Add to librechat.yaml and set MAGUYVA_API_KEY in the LibreChat server’s environment:

librechat.yaml 
mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

This config reads your key from the MAGUYVA_API_KEY environment variable. Set it to your API key from app.maguyva.ai in the environment your client starts from.

LibreChat MCP docs →

Antigravity

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

Add to your Antigravity MCP configuration:

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

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

What Maguyva adds to Antigravity →

Antigravity MCP docs →

Claude Cowork

Claude Cowork does not load servers from claude_desktop_config.json; it reaches remote servers as custom connectors. In Customize → Connectors, add a custom connector with the URL https://maguyva.tools/mcp, choose No sign-in, and add an authorization request header whose value is Bearer followed by your API key. Request headers are in beta for a limited set of organizations; if the dialog has no Request headers section, Cowork cannot authenticate to Maguyva yet. See 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

Add to ~/.warp/.mcp.json (or .warp/.mcp.json in a project), or paste it into Settings → Agents → MCP servers → + Add:

~/.warp/.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

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

What Maguyva adds to Warp →

Warp MCP docs →

Maguyva uses standard MCP. Any client that supports the protocol can connect — even if there is no first-party guide above. 23 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 check repository resolution. A repository override applies only to the current call.

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

#
  • If your client uses the @maguyva/mcp bridge, 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

#

Related

Read next