TopoloMCP

Model Context Protocol server for the Topolo platform. Lets MCP-capable agents (Claude Desktop, Claude Code, Codex, Cursor, etc.) call Topolo APIs as native tools rather than shelling out.

Why both a CLI and an MCP server?

• The CLI (@topolo/cli) is for humans, shell scripts, and agents without MCP support.
• The MCP server (@topolo/mcp) is for agents that speak the protocol natively — it gives them typed tool schemas, scope-filtered tool advertisement, and structured error responses. Both wrap the same @topolo/sdk.

Install

npm install -g @topolo/mcp

You don't have to install globally — the registration snippets below use npx so the server downloads on demand.

Get a credential

Either:

• Long-lived: mint an API key at the Topolo Developers console (TOPOLO_API_KEY=topo_live_...). Preferred for persistent agent installs.
• Short-lived: topolo auth login with the CLI, then copy the access token from ~/.config/topolo/config.json. Useful for dev and testing. MCP does not read the CLI config directly; pass the token in TOPOLO_ACCESS_TOKEN.

Register with an MCP client

Claude Code

claude mcp add topolo -- npx -y @topolo/mcp

Then set the credential and (optional) agent label in your shell profile so Claude Code inherits them when it spawns the server:

export TOPOLO_API_KEY=topo_live_...
export TOPOLO_AGENT_NAME=claude-code

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "topolo": {
      "command": "npx",
      "args": ["-y", "@topolo/mcp"],
      "env": {
        "TOPOLO_API_KEY": "topo_live_...",
        "TOPOLO_AGENT_NAME": "claude-desktop"
      }
    }
  }
}

Codex / Cursor / generic MCP host

Any MCP host that spawns a stdio subprocess works. Point command at npx -y @topolo/mcp and pass the same env vars. Most Codex-style setups also read AGENTS.md files — see @topolo/cli's skills/codex/AGENTS.md for a ready-made agent guide that covers both the CLI and this MCP.

Supported env vars

| Var | Purpose | | ---------------------------- | ----------------------------------------------------- | | TOPOLO_API_KEY | Platform API key (preferred) | | TOPOLO_ACCESS_TOKEN | Short-lived JWT (dev/testing) | | TOPOLO_AGENT_NAME | Human-readable agent label for audit logs | | TOPOLO_SERVICE_URL_<ID> | Override a service base URL (e.g. _AUTH, _CRM) |

Exactly one credential var must be set. If both are present, TOPOLO_API_KEY wins.

Startup sequence

1. Resolve the credential from env. Refuse to start if none is set.
2. Call GET /api/me to load the user's granted scopes + role.
3. Filter TOOLS by those scopes — agents never see a tool they cannot use.
4. Connect the stdio transport and begin serving MCP requests.

Startup is synchronous and fast (< 500 ms typical). If the credential is rejected, the process logs the error to stderr and exits non-zero — host clients surface that as a failed server launch.

Tools

| Tool | Required scopes | Destructive hint | | ---------------------------- | --------------------- | ---------------- | | topolo_whoami | (none) | no | | topolo_list_services | (none) | no | | topolo_list_applications | (none) | no | | topolo_get_application | (none) | no | | topolo_list_application_requirements | (none) | no | | topolo_audit_applications | (none) | no | | topolo_crm_list_contacts | crm.contacts:read | no | | topolo_crm_get_contact | crm.contacts:read | no | | topolo_api_call | (service-enforced) | yes |

topolo_api_call is the escape hatch for endpoints without typed MCP tools yet. GET requests work without confirmation; mutating HTTP methods must pass confirm: true or the SDK rejects the call. Backing services still enforce permissions for every request.

Safety rails

• No orgId parameter on any tool. The organization is derived entirely from the credential by each backend app. There is no path for Org A's agent to see Org B's data.
• Scope-gated tool advertisement. Agents never see tools they can't use — fewer wasted attempts and less prompt noise.
• Audit headers. Every request sends X-Topolo-Client: topolo-mcp/<ver>, X-Topolo-Agent: <label>, X-Topolo-Request-Id: <uuid>.
• Write-action confirmation. The SDK refuses mutating HTTP methods unless the call explicitly passes confirm: true. Mutating tools (when introduced) will require the host client to approve before invocation.

Troubleshooting

• "TOPOLO_API_KEY or TOPOLO_ACCESS_TOKEN must be set" — no credential reached the subprocess. In Claude Desktop, double-check the env block in claude_desktop_config.json. In Claude Code, the server inherits your shell env, so make sure the var is exported in the profile your launcher reads.
• "credential rejected" — token is expired or revoked. For API keys, mint a fresh one. For access tokens, re-run topolo auth login and copy the new token.
• Tool missing from the list — the credential doesn't grant the required scope. Check topolo whoami to see the current scopes; either broaden the API key's permissions or switch to one that already has them.
• Tool call returns Permission denied — the scope check on the backend disagrees with startup introspection (rare, but possible across scope changes). Re-spawn the server to refresh the cached scope set.

Development

cd TopoloMCP
npm install
npm run build
TOPOLO_API_KEY=topo_live_... node dist/index.js

The server speaks MCP over stdio; when running standalone it just blocks waiting for JSON-RPC on stdin. To drive it manually, use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Release flow

Pushing a v<x.y.z> tag to main triggers GitHub Actions to typecheck, test, build, verify the tag matches package.json, and publish to npm via the NPM_TOKEN secret. No developer-machine credentials involved.

Phase 2 (planned)

• More typed tools as @topolo/sdk modules ship.
• HTTP transport in addition to stdio, for hosted (non-subprocess) deployments.
• Optional --provenance on npm publish once the repo is public.