MCP API scoping

When you call tools/list, the gateway builds the list from your authorized integration connections and available first-party Platform tools, then applies your organization’s server and tool permissions. Platform tools do not require an integration connection. Discovery does not grant access to every resource a tool can act on; each call checks access to the requested resource.

What you see in tools/list

A tool needs at least one of these access paths to appear:

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 an available first-party Platform tool — Platform MCP must be configured, and the tool must meet its discovery requirements. Audit, organization management, directory, and department tools, and the model write tools (platform_delete_model, platform_set_model_deployment_priority), are omitted unless you meet their role and plan requirements. 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.

The tool must also pass your organization’s server and tool permissions. The organization’s approval setting applies to external MCP: Run automatically permits otherwise-authorized tools, while Ask before running and Block omit them from tools/list and prevent execution.

Your personal tool approval settings apply to Kindo chats and agents. They do not restrict external MCP access or override organization restrictions. Configure which permitted tools to use and when to request approval in your external client.

Every tools/call checks the current organization settings again, including calls using a previously discovered tool name. Platform audit, organization, directory, department, and model write calls also recheck their role and plan requirements, so a tool discovered before access was revoked cannot bypass those checks. An organization requirement for manual approval returns manual_approval_required; use Kindo chat if manual approvals are enabled for your organization, or contact your administrator. An organization Block setting returns the invalid-params error (-32602).

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 agent — the gateway accepts an allow-list as either a query parameter or a header:

# 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?

The bare list includes eligible tools across the integrations 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 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

• Quickstart — first call.
• Request shape — supported methods and headers.
• Kindo extensions — the connection- management REST endpoints used by step 2.