Gateco MCP server

Install

The MCP server is an optional extra on the gateco Python package. Install it with the [mcp] extra:

pip install "gateco[mcp]"

This pulls in mcp>=1.8,<2 (FastMCP) alongside the core SDK and CLI. Users who only need the SDK or CLI are unaffected — the mcp dependency is never installed unless explicitly requested.

After installation, two entry points are available:

gateco mcp serve    # via the unified CLI
gateco-mcp          # direct entry point for MCP host configs

Both start the MCP server on stdio transport. MCP hosts (Claude Desktop, Cursor) manage the process lifecycle — you never run it directly.

Credentials

The MCP server resolves credentials in this order:

1. GATECO_API_KEY environment variable — recommended for MCP host configs. Set it in the env block of your host configuration (see below).
2. GATECO_BASE_URL environment variable — override the API endpoint. Defaults to https://api.gateco.ai. Set this if you are on an Enterprise private data plane.
3. ~/.gateco/credentials.json — written by gateco login. Used as a fallback when neither env var is set. Not recommended for MCP host configs — prefer the env var for explicit, auditable credential binding.

Generate an API key in your Gateco dashboard under Settings → API Keys.

Claude Desktop setup

Add Gateco to your Claude Desktop MCP server config. The config file location depends on your OS:

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

Add a gateco entry under mcpServers:

{
  "mcpServers": {
    "gateco": {
      "command": "gateco-mcp",
      "env": {
        "GATECO_API_KEY": "gco_your_api_key_here",
        "GATECO_BASE_URL": "https://api.gateco.ai"
      }
    }
  }
}

Restart Claude Desktop after saving. The six Gateco tools appear in the tool selector. Claude will call them automatically when answering questions that require searching your knowledge base.

If gateco-mcp is not on your PATH (e.g., installed in a virtualenv), use the full path: /path/to/venv/bin/gateco-mcp.

Cursor setup

Cursor reads MCP server configs from ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project root (project-scoped).

{
  "mcpServers": {
    "gateco": {
      "command": "gateco-mcp",
      "env": {
        "GATECO_API_KEY": "gco_your_api_key_here",
        "GATECO_BASE_URL": "https://api.gateco.ai"
      }
    }
  }
}

Open Cursor Settings → Features → MCP to verify the server is listed and shows a green status indicator. Project-scoped configs take precedence over the global config when both are present.

Use the project-scoped config (.cursor/mcp.json) to bind different API keys per codebase — useful when different projects connect to different Gateco organizations or environments.

Other MCP hosts

Any MCP-compatible host that supports stdio transport can use the Gateco server. The command is always gateco-mcp (or the full path to the binary). Pass GATECO_API_KEY and optionally GATECO_BASE_URL as environment variables.

For programmatic use or testing, you can also start the server directly:

GATECO_API_KEY=gco_your_key gateco mcp serve

Tools reference

The Gateco MCP server exposes six tools. All tools return human-readable markdown — not raw JSON. Denied content is never included in tool output; only denial reasons and counts are surfaced.

Passing identity to retrieval tools

gateco_retrieve and gateco_ask require either a principal_id (UUID) or an email address. When you pass an email, the MCP server resolves it to a principal UUID automatically before executing the retrieval — no pre-resolution step in the agent runtime.

See Agent identity patterns for a full explanation of the three integration patterns — including how to handle external users (customers, partners) who don't have a corporate directory entry.

How policy enforcement works through MCP

Every call to gateco_retrieve or gateco_ask runs the full Gateco policy engine before returning results to the MCP host. The sequence:

1. Search the connector using the requested mode (vector / keyword / hybrid / grep)
2. Resolve the requesting principal and load their IDP-synced attributes
3. Evaluate all active policies against each candidate chunk
4. Return only the allowed chunks — denied chunks are dropped, not redacted
5. Write a SecuredRetrieval audit event with full policy trace

The MCP host (and therefore the LLM) never sees denied content — not even a truncated excerpt. Denial reasons and counts are included in the tool output so the model can surface a meaningful response rather than silently omitting data.

Rate limits apply per organization: 60 retrievals/min for gateco_retrieve, 20/min for gateco_ask, and 10/min for gateco_check_access. Exceeded limits return a rate_limited error string that the MCP host surfaces to the user.

Troubleshooting

Still stuck? Contact support with your Gateco organization ID and the error message from the MCP host log.