# Installation Guide

Canonical source: https://maguyva.ai/docs/installation

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Get up and running in under 5 minutes. This guide includes setup for 23 MCP clients including Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT, and Warp, and more.

**Prerequisites**: You'll need an API key from [app.maguyva.ai](https://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)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

Replace `mgv_xxxx` with your actual API key from [app.maguyva.ai](https://app.maguyva.ai).

## Client Configuration

Choose your MCP client below for specific setup instructions.

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

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](https://maguyva.ai/docs/troubleshooting) 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

- MCP API Reference: Complete API documentation
- How It Works: Understand context optimization
- Troubleshooting: Fix setup and connection issues