Skip to content
Kindo Kindo Docs

MCP API scoping

When you call tools/list, the gateway returns only the tools your API key is entitled to use. The list is built per-call from your account’s connections — there is no separate enrollment step.

What you see in tools/list

You see a tool if any of these is true:

  1. You personally have a connection to that integration — e.g., you connected your own Linear or GitHub account in Kindo.
  2. Someone in your org has shared a connection with you — a teammate’s connection that your account is allowed to use.
  3. The integration is public — no credentials required, like the built-in browser integration.

If none of these is true for a given integration, none of its tools appear in tools/list, and a direct tools/call on one of those tools returns the protocol’s invalid-params error.

You don’t need to pass any filter or flag to get this behavior. The bare POST /v1/mcp endpoint returns the right list for your account by default.

Narrowing the list

For agents that only need a subset of your tools — for example, a Linear-only workflow — the gateway accepts an allow-list as either a query parameter or a header:

Terminal window
# Query parameter
curl -X POST "https://api.kindo.ai/v1/mcp?integrations=linear,github" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $KINDO_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'


# Header (equivalent)
curl -X POST https://api.kindo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $KINDO_API_KEY" \
  -H "x-kindo-integrations: linear,github" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

The filter narrows the set you would otherwise see — it never grants access. If your account doesn’t have a path to GitHub and you pass ?integrations=linear,github, you get only Linear tools back (no error). Names in the filter must match the integration ID exactly (e.g., linear, github, sap-s4hana-rfc).

Both forms accept comma-separated values. The query parameter also accepts array repetition (?integrations=linear&integrations=github). If both query and header are present, the query parameter wins. A missing or empty filter value is ignored.

Why narrow?

The bare list reflects every integration your API key can reach. For accounts with broad shared connections that can be 1000+ tools — enough to exceed most chat clients’ context windows. A narrow filter keeps the tool surface small:

  • Context-budget reasons. Many MCP clients send the full tool catalog to the model on every turn. Fewer tools means a smaller system prompt and more room for actual work.
  • Per-agent focus. Pin a single MCP client to one or two integrations even though your API key has access to more.
  • Stable surface. Decouple your client from new integrations added to your org later.

Default-connection resolution

When your account has more than one connection for the same integration — say, two Linear accounts — the gateway has to pick one for every tools/call. The resolution chain is:

  1. Only one connection. Use it.
  2. You set a preferred default. Kindo uses the one you pinned via POST /v1/integrations/connections/{integration_id}/default (see Kindo extensions).
  3. You own at least one connection. Use your most recently created owned connection.
  4. You don’t own any, but a shared one is available. Use the most recently created shared connection.

If the chosen connection’s credentials have been revoked or expired, the call returns a credentials_unavailable error with a hint to reconnect. See Errors for the exact envelope.

See also