Metis MCP Server

Metis exposes code intelligence tools through MCP (Model Context Protocol) so AI assistants can answer dependency, blast-radius, and symbol-discovery questions against indexed repositories.

Supported Clients

• Cursor
• VS Code native MCP
• GitHub Copilot in VS Code
• Claude Code

Client-specific setup guides:

• docs/setup-copilot.md
• docs/setup-claude-code.md
• docs/setup-vscode.md

Current Package Version

The currently published npm package version is 1.0.3.

Use that version in npx or pinned install examples unless/until 1.0.3 is published.

Installation

npm install -g @arbotdev/[email protected]

Or use it directly with npx:

npx -y @arbotdev/[email protected]

Security Model

• Access is controlled by METIS_API_TOKEN, a JWT issued by Metis.
• Your token's repo_allowlist controls which repositories you can search, inspect, and fetch snippets from.
• Standard pilot tokens should not include internal arbotdev repositories unless explicitly granted.
• The MCP server is a thin client-side wrapper over the Metis API. It does not bypass Metis authorization.

Configuration

1. Get a JWT Token

Contact your Metis administrator to get a JWT token for the repositories you should be able to access.

2. Configure Your Client

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "metis": {
      "command": "npx",
      "args": ["-y", "@arbotdev/[email protected]"],
      "env": {
        "METIS_API_URL": "https://metis-api-13539721132.us-central1.run.app",
        "METIS_API_TOKEN": "YOUR_JWT_TOKEN_HERE"
      }
    }
  }
}

VS Code Native MCP / Copilot in VS Code

Add to .vscode/mcp.json or your user MCP config:

{
  "servers": {
    "metis": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@arbotdev/[email protected]"],
      "env": {
        "METIS_API_URL": "https://metis-api-13539721132.us-central1.run.app",
        "METIS_API_TOKEN": "YOUR_JWT_TOKEN_HERE"
      }
    }
  }
}

Claude Code

claude mcp add --transport stdio --scope local \
  --env METIS_API_URL=https://metis-api-13539721132.us-central1.run.app \
  --env METIS_API_TOKEN=YOUR_JWT_TOKEN_HERE \
  metis -- npx -y @arbotdev/[email protected]

3. Restart Or Reload

• Cursor: restart the app after changing mcp.json
• VS Code: restart or reload if prompted
• Claude Code: verify with claude mcp list or /mcp

Tools

| Tool | Description | |------|-------------| | metis_plan_change | Plan a code change with blast radius and an explanation | | metis_explain_impact | Get inbound blast radius and impact analysis for a symbol | | metis_get_callees | Get the outbound call graph for a symbol | | metis_search | Search for symbols in the codebase | | metis_resolve | Resolve a symbol from file and line position | | metis_get_snippet | Get raw or smart-expanded code snippets | | metis_traceback | Analyze a Python traceback against the code graph | | metis_trace_symbol | Trace symbol lineage across the codebase | | metis_trace_enum | Trace enum or typed constant values to handlers | | metis_doctor | Check authentication, health, and repo access |

Quick Verification

Ask your client:

Run metis doctor to check my connection

Then try:

What calls validate_token?

And:

Find the AuthService class

Usage Examples

• "What will this change break?" → metis_plan_change
• "What calls this function?" → metis_explain_impact
• "What does this function call?" → metis_get_callees
• "Find the UserAuth class" → metis_search
• "Show me the code for that function" → metis_get_snippet
• "Analyze this traceback" → metis_traceback
• "Trace this symbol's lifecycle" → metis_trace_symbol
• "Check my Metis connection" → metis_doctor

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | METIS_API_TOKEN | Yes | - | JWT token for authentication and repo-scoped access | | METIS_API_URL | No | https://metis-api-13539721132.us-central1.run.app | Metis API base URL | | PORT | No | 8080 | HTTP MCP bind port for start:http | | HOST | No | 0.0.0.0 | HTTP MCP bind host for start:http | | MCP_HTTP_CORS_ORIGIN | No | unset | Optional CORS origin for browser-based MCP clients |

Experimental HTTP Mode

The repo also includes an HTTP MCP entrypoint for pilot rollout work:

npm run build
PORT=8080 node dist/http-server.js

Notes:

• The server binds to 0.0.0.0:$PORT for Cloud Run compatibility.
• HTTP requests must include Authorization: Bearer <metis-jwt>.
• The incoming bearer token is forwarded as the request-scoped Metis identity, so downstream repo access still follows the token's repo_allowlist.
• If you need browser-based access, set MCP_HTTP_CORS_ORIGIN explicitly instead of defaulting to *.

Troubleshooting

"Authentication Not Configured"

The METIS_API_TOKEN environment variable is not set in your MCP client config.

"REPO_NOT_ALLOWED"

Your token does not include that repository in its repo_allowlist. Request the correct access instead of changing the client config.

"TOKEN_EXPIRED"

Your JWT has expired. Request a new token.

MCP server does not start

• Confirm Node.js 18+
• Try running manually:

npx -y @arbotdev/[email protected]

License

MIT