Skip to content
KindoKindo 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 authorized integration connections and first-party Platform tools enabled for your account. Platform tools do not require an integration connection.

What you see in tools/list

Section titled “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.
  4. It is a first-party Platform tool enabled for your account — these tools do not use an integration connection.

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

Section titled “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, platform, 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?

Section titled “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

Section titled “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 to that connected integration. First-party Platform tools do not use a connection or a default. The resolution chain for connected integrations is:

  1. Only one connection. Use it.
  2. You selected active connections. Kindo uses the first usable connection in your active set. You can also replace that set with one preferred connection 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.

Kindo chats and agents can choose an account for each tool call from your active connections or their pinned connections. External MCP clients use one connection per integration, selected by the resolution chain above; their tools do not expose a per-call account selector. Platform tools remain connectionless.

See also

Section titled “See also”