> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invokehq.run/llms.txt
> Use this file to discover all available pages before exploring further.

# invoke-mcp

> Connect Claude, Cursor, or a custom agent to Invoke's MCP control plane for context, policy simulation, approvals, traces, and governance checks.

Invoke exposes an MCP endpoint so agents can inspect the execution layer before touching production tools.

```text theme={null}
https://invokehq.run/v1/mcp
```

Use MCP for control-plane actions:

* discover Invoke tools
* query company brain context
* simulate policy before execution
* run preflight checks
* inspect approvals and execution records
* summarize observability and governance readiness

Do not give MCP clients a full production key by default. Start with the `mcp_readonly` profile.

## Create a scoped MCP key

Issue a key with the MCP read-only profile:

```bash theme={null}
curl -X POST "$INVOKE_BASE_URL/v1/beta/users/$USER_ID/keys" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $INVOKE_ADMIN_KEY" \
  -d '{
    "name": "Claude desktop MCP",
    "profile": "mcp_readonly"
  }'
```

The profile grants:

```json theme={null}
{
  "scopes": [
    "tools:read",
    "brain:read",
    "policy:simulate",
    "traces:read",
    "approvals:read",
    "observability:read",
    "governance:read"
  ],
  "allowed_tools": ["invoke.company_brain.query"],
  "read_only": true
}
```

Fetch available profiles:

```bash theme={null}
curl https://invokehq.run/v1/mcp/key-profiles
```

## Smoke test production

Run the checked-in smoke script:

```bash theme={null}
export INVOKE_BASE_URL="https://invokehq.run"
export INVOKE_API_KEY="inv_live_..."
venv/bin/python scripts/test_mcp_smoke.py
```

The smoke test calls:

1. `GET /v1/mcp`
2. `initialize`
3. `tools/list`
4. `tools/call invoke.policy.simulate`

It intentionally does not mutate production systems.

## JSON-RPC examples

List tools:

```bash theme={null}
curl -X POST https://invokehq.run/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $INVOKE_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

Simulate a dangerous action:

```bash theme={null}
curl -X POST https://invokehq.run/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $INVOKE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "invoke.policy.simulate",
      "arguments": {
        "agent_id": "finance_agent",
        "action": "database.execute",
        "params": {"sql": "drop table invoices"}
      }
    }
  }'
```

Query company brain:

```bash theme={null}
curl -X POST https://invokehq.run/v1/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $INVOKE_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "invoke.company_brain.query",
      "arguments": {
        "query": "Acme",
        "entity_type": "customer",
        "join_to": {"entity_type": "invoice"}
      }
    }
  }'
```

## Claude Desktop config

Use an MCP bridge that supports streamable HTTP or a small local proxy that forwards JSON-RPC to Invoke:

```json theme={null}
{
  "mcpServers": {
    "invoke": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://invokehq.run/v1/mcp",
        "--header",
        "X-API-Key:${INVOKE_API_KEY}"
      ],
      "env": {
        "INVOKE_API_KEY": "inv_live_..."
      }
    }
  }
}
```

## Next steps

* [Approvals](/concepts/approvals) — review and thaw risky actions
* [Traces](/concepts/traces) — inspect execution receipts
* [Environment variables](/configuration/environment-variables) — configure backend and frontend URLs