Skip to content

Installation Guide

Get up and running in under 5 minutes. This guide currently includes step-by-step setup for 8 documented MCP clients: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Goose, LM Studio, and Claude Cowork.

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.

Experimental note: Gemini CLI may work, but MCP support is not yet confirmed. ChatGPT supports MCP via Developer Mode on Business and Enterprise plans.

Claude Code 
# Install MCP server via Claude Code CLI
claude mcp add maguyva -e MAGUYVA_API_KEY=mgv_xxxx -- npx -y @maguyva/mcp

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

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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.

Cursor

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

.cursor/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.

VS Code (GitHub Copilot)

Add to your VS Code settings (settings.json):

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

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

Windsurf

Add to your Windsurf MCP configuration:

windsurf_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.

Goose

Add to goose.yaml:

goose.yaml 
mcp_servers:
  maguyva:
    command: npx
    args:
      - "-y"
      - "@maguyva/mcp"
    env:
      MAGUYVA_API_KEY: "mgv_xxxx"

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

LM Studio

Add to your LM Studio MCP configuration:

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

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

Gemini CLI

Experimental: Gemini CLI may work, but MCP support is not yet confirmed. ChatGPT supports MCP via Developer Mode on Business and Enterprise plans. Check Google's documentation for the latest on MCP compatibility.

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" (uses main branch)

Tip: Set a session default with repository_context(action="set", repository="...") to avoid repeating it in every 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 #

  • 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 #

MAGUYVA.NFO