Mantis MCP Server

The Mantis MCP server gives AI tools read-only access to Insight traces, observations, scores, and analytics through the Model Context Protocol. Use it with Cursor, Claude Desktop, or any MCP-compatible client that can launch a local stdio server.

Prerequisites

• An active Insight account.
• Node.js and npm.
• Cursor, Claude Desktop, or another MCP-compatible client.
• A personal access token from Insight, or a project API key pair.

Create a personal access token

Personal access tokens are the recommended auth mode for MCP clients because they can list every project your user can read.

1. Open the Insight web app.
2. Click your account menu in the lower-left sidebar.
3. Open Account Settings.
4. Select Access Tokens.
5. Click Create Token.
6. Give the token a recognizable name, then copy it immediately.

Install

Global command

npm install -g @mantisai/mcp
mantis-mcp --help

npx

npx -y @mantisai/mcp --help

MANTIS_URL defaults to https://insight.withmetis.ai, so production setup usually only needs a token.

Configure Cursor

Open Cursor settings, go to Tools & MCP, and add a new MCP server named mantis.

Use one of these configurations.

npx config

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["-y", "@mantisai/mcp", "serve"],
      "env": {
        "MANTIS_API_TOKEN": "pat_..."
      }
    }
  }
}

Global command config

{
  "mcpServers": {
    "mantis": {
      "command": "mantis-mcp",
      "args": ["serve"],
      "env": {
        "MANTIS_API_TOKEN": "pat_..."
      }
    }
  }
}

For a local or self-hosted Insight instance, set MANTIS_URL too:

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["-y", "@mantisai/mcp", "serve"],
      "env": {
        "MANTIS_URL": "http://localhost:3000",
        "MANTIS_API_TOKEN": "pat_..."
      }
    }
  }
}

After saving the config, reload MCP servers or restart Cursor. The mantis server should show as connected and expose Insight tools in chat.

Configure Claude Desktop

Add the same server block to claude_desktop_config.json:

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["-y", "@mantisai/mcp", "serve"],
      "env": {
        "MANTIS_API_TOKEN": "pat_..."
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Authentication modes

PAT mode requires the AI client to pass project_id when calling most project-specific tools. Use list_projects first to find the right ID.

Project key mode is already scoped by the key pair, so project-specific tools do not need an explicit project_id.

Available tools

Tools are discovered dynamically from the Insight backend. Common tools include:

Direct HTTP MCP

MCP-compatible agents can connect directly to the hosted endpoint without running the local stdio proxy.

curl -X POST "https://insight.withmetis.ai/api/public/mcp?project_id=$MANTIS_PROJECT_ID" \
  -H "Authorization: Bearer $MANTIS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Use direct HTTP MCP when your agent framework supports HTTP MCP transport. Use the stdio server for tools like Cursor and Claude Desktop that launch a local command.

Verify

Cursor or Claude Desktop

1. Reload or restart the client.
2. Confirm the mantis server is connected.
3. Ask the client to list available Mantis projects.
4. Pick a project ID and ask for a project summary or recent traces.

Example prompt:

Use the Mantis tools to list my Insight projects, then describe the project with the most recent trace data.

Terminal

Run the server with environment variables to confirm it can start and discover projects:

MANTIS_API_TOKEN="pat_..." npx -y @mantisai/mcp serve

The process stays open because stdio MCP servers wait for a client connection. Startup logs should show accessible projects and then that the MCP server is running on stdio.

Security model

MCP tool calls are read-only. Insight enforces:

• Authentication on every request.
• Project scoping for every tool call.
• ClickHouse readonly=1 for SQL execution.
• A table allowlist for analytics queries.
• Execution timeouts and result limits.

The MCP package should still be treated as a credentialed local process. Keep tokens out of source control, do not paste PATs into chats, and remove old tokens when a machine or config is no longer trusted.

Troubleshooting

mantis-mcp: command not found

Use the npx config, or reinstall globally:

npm install -g @mantisai/mcp

If global install still fails, make sure your npm global bin directory is on PATH.

Server connects, but no projects appear

The PAT may not have access to any Insight projects. Confirm you can open the project in the Insight web app, then create a new token from that same account.

401 or auth errors

The token or key pair is missing, expired, revoked, or copied incorrectly. Delete the old token and create a fresh one from Account Settings -> Access Tokens.

Cursor shows the server as disabled

Toggle the server on from Settings -> Tools & MCP. If it turns off again, inspect the MCP server logs and verify the configured command works in a normal terminal.

Tool calls ask for project_id

That is expected in PAT mode. Run list_projects, copy the project ID, and include it in the tool call.

Next steps

• Insight CLI
• Insight SQL API
• Insight REST API