Integrations and tool policy (admin API)
For developers and administrators who manage an organization's integrations over MCP. An integration is an MCP server, an MCP registry, a GitHub repository of skills, an A2A agent or an API that the organization adds once. Its instructions can then name what it offers, the editor offers it as people write, and admins decide which of a server's tools may be used. This page covers every orgs_integrations_* tool, the OpenAPI import, the tool policy and where each decision takes effect.
The same settings are in the editor under Settings ▸ Integrations, one page for each kind: Servers, Registries, Skills, Agents, APIs and Directories. People directories are on SCIM and people directories.
Before you start
Plans On Pro, Team, and Enterprise
- Plan. Adding integrations needs the plan above. Allowing and blocking tools, and Only approved integrations, have their own badges in their sections.
- Who can do this. The tools that change something are for an organization's owners and admins, as people, with a token that has the
org:adminscope. Agent credentials can't call them. The tools that only read (orgs_integrations_list,orgs_integrations_search,orgs_integrations_tools_list) are for any member, agent credentials included. See org:admin. - What you need. The organization's id (
org_…, fromsession_bootstrapororgs_list), and the https address of what you add. Everything the server pulls must be on a public https address.
The tools
| Tool | What it does | Who | Effect |
|---|---|---|---|
orgs_integrations_list | Every integration with its state, its last pull's note and counts, and the plan's features. | Any member | read |
orgs_integrations_add | Add an MCP server, an MCP registry, a GitHub repository of skills or an A2A agent; the pull runs in the background. | Owner or admin | write |
orgs_integrations_sync | Pull an integration again now. | Owner or admin | write |
orgs_integrations_remove | Remove an integration and everything it offered. | Owner or admin | destructive |
orgs_integrations_search | Find the items the integrations offer, or ask which of some targets they approve and which tools are blocked on them. | Any member | read |
orgs_integrations_tools_list | An MCP server's tools, or an API's operations, each allowed or blocked, and the default for new ones. | Any member | read |
orgs_integrations_tools_set | Allow or block tools, or change what a tool found for the first time gets. | Owner or admin | destructive |
orgs_integrations_apis_add | Add an API from its OpenAPI document, read in the request. | Owner or admin | write |
orgs_integrations_apis_pull | Read an API's document again. | Owner or admin | write |
Every argument of each tool is on MCP tools. The ones this page uses most are listed in their sections.
Add an MCP server, a registry, skills or an agent
orgs_integrations_add takes one of these kinds:
kind | What it is | url | What a pull keeps |
|---|---|---|---|
mcp | An MCP server | Its Streamable HTTP endpoint, such as https://mcp.example.com/mcp | What it says it is and its tools with their input schemas, when it answers without sign-in |
registry | An MCP registry | The registry's base address (its /v0.1/servers API) | Its servers' latest versions, each an MCP server item; search narrows them |
skills | A GitHub repository of skills | https://github.com/<owner>/<repository> | Every SKILL.md of the branch (default: the repository's) and folder (default: all of it) |
agent | An A2A agent | Its Agent Card (a .json or /.well-known/ address) or its endpoint | Its Agent Card: name, interfaces and skills; with no card, the agent is known by its endpoint |
kind takes only these four. An API is added with orgs_integrations_apis_add (below), and a people directory with orgs_people_directories_add.
Add it
Call
orgs_integrations_addwith the kind and the address. Pass anidempotencyKeyso a retried call answers what the first one did.tools/call params{ "name": "orgs_integrations_add", "arguments": { "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "kind": "mcp", "url": "https://calendar.example.com/mcp", "title": "Calendar", "idempotencyKey": "add-calendar-2026-11-22" } }The answer comes at once, with the integration in the state
syncing:Answer{ "integration": { "id": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "kind": "mcp", "url": "https://calendar.example.com/mcp", "title": "Calendar", "options": {}, "state": "syncing", "createdAt": "2026-11-22T09:14:03.120Z", "tools": 0, "blockedTools": 0, "newTools": "allow" } }Wait for the pull
The server pulls what the address describes in the background. Read
orgs_integrations_listuntil the state isreadyorerror:orgs_integrations_list{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "integrations": [ { "id": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "kind": "mcp", "url": "https://calendar.example.com/mcp", "title": "Calendar", "options": {}, "state": "ready", "items": 1, "syncedAt": "2026-11-22T09:14:05.871Z", "createdAt": "2026-11-22T09:14:03.120Z", "tools": 12, "blockedTools": 0, "newTools": "allow" } ], "integrationsOnly": false, "features": { "integrations": true, "integrationsOnly": true, "toolPolicy": true } }itemsis how many objects the pull kept. For an MCP server,toolsandblockedToolscount its tools.notesays what the pull wants you to know, such as a list cut short.Check what it offers
For an MCP server, list its tools with
orgs_integrations_tools_list(below). For the other kinds,orgs_integrations_searchwith aquerylists the items, and the editor offers them as people type&and@.
Other kinds take their own options:
{ "name": "orgs_integrations_add", "arguments": { "orgId": "org_01JX…", "kind": "registry",
"url": "https://registry.modelcontextprotocol.io", "search": "github" } }
{ "name": "orgs_integrations_add", "arguments": { "orgId": "org_01JX…", "kind": "skills",
"url": "https://github.com/acme/agent-skills", "branch": "main", "path": "support" } }
{ "name": "orgs_integrations_add", "arguments": { "orgId": "org_01JX…", "kind": "agent",
"url": "https://agents.example.com/.well-known/agent-card.json" } } registry:searchkeeps only the servers whose name has those words.skills:branch(default: the repository's default branch) andpath, a folder (default: the whole repository). The address must behttps://github.com/<owner>/<repository>; a trailing.gitor slash is dropped.title, for every kind: the name shown (default: what the source calls itself).
Arguments of orgs_integrations_add
| Argument | Type | Required | What it is |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
kind | "mcp" | "registry" | "skills" | "agent" | yes | What it is: an MCP server's endpoint, an MCP registry, a GitHub repository of skills, an A2A agent (its Agent Card or its endpoint). |
url | string | yes | Its https:// address. |
title | string | Its name (default: what it calls itself). | |
branch | string | Skills: the branch (default: the repository's). | |
path | string | Skills: the folder to look in (default: the whole repository). | |
search | string | Registry: only the servers whose name has this. | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
The pull and its states
state |
Editor | What it means |
|---|---|---|
syncing |
Pulling… | A pull is queued or running. |
ready |
Ready | The last pull finished. What it kept replaced the pull before. note may still say something went partly wrong. |
error |
Didn't pull | The last pull failed. note says why. What an earlier pull kept stays. |
How each kind is pulled:
- Only public https. Every request goes to a public https address. Private, loopback, link-local and reserved addresses are refused, and so is a host name that resolves to one. A redirect is followed at most 3 times, each checked again.
- Each request has a 15-second timeout and a 2 MB answer cap.
- An MCP server is asked for
initializeandtools/list, without credentials. One that answers 401 or 403 is kept by its address, with the note "The server asks for sign-in, so its tools aren't listed". One that fails otherwise is kept the same way, with "Couldn't list its tools: …". Up to 300 tools are kept, each with its input schema when that is 8 KB or less. - A registry is read 100 servers a page, up to 50 pages. Past that, the note says "Kept the first N servers; a search narrows what is pulled".
- A skills repository keeps up to 200
SKILL.mdfiles. Past that, the note says "Kept 200 of N skills; a folder narrows what is pulled". A repository with none says "No SKILL.md found". - An agent is read from its Agent Card. Given an endpoint, the server tries
/.well-known/agent-card.json, then/.well-known/agent.json. With no card, the agent is kept by its endpoint alone, and the note says so.
The server pulls only when you add an integration or ask for a pull. It never pulls again on its own.
Pull again, and remove
- Pull again.
orgs_integrations_syncwith theintegrationIdsets the state tosyncingand queues a pull. Adding the same kind, address and options again does the same, and keeps a newtitleif you give one; it doesn't make a second integration. An API is pulled withorgs_integrations_apis_pullinstead. - Remove.
orgs_integrations_removedeletes the integration with everything it offered and every tool decision made on it. Instructions keep what they wrote. Where Only approved integrations is on, the objects it approved show as not approved. Added again later, it starts from the defaults.
How many
An organization keeps at most 100 integrations, every kind counted, APIs and people directories too. The next one is refused with limit_reached, "an organization keeps at most 100 integrations; remove one first". Adding or pulling one again that already exists doesn't count. Every other limit is on Rate and size limits.
Import an API from its OpenAPI document
orgs_integrations_apis_add adds an API from its OpenAPI document: OpenAPI 3.0, 3.1 or Swagger 2.0, in JSON or YAML. The server reads the document during the call, not as a background job, and answers with what it found.
- Where the document comes from. Give its https
url, or the document itself asdocument(an upload of 5 MB or less, withfileNameto know it by). Give exactly one of the two. A document fetched from a URL has the same cap. - Each operation becomes a tool. Every operation with an
operationIdbecomes a tool that instructions can name, with its method, path, input schema (its parameters, and its JSON body asbody) and output schema (its first success). An operation without anoperationIdis left out, and the note counts them. - Reads are allowed, writes are blocked. An operation whose method is
GETorHEADstarts allowed. Every other method starts blocked until an admin allows it. Change them withorgs_integrations_tools_set, as for an MCP server. - Large APIs. An API keeps at most 300 operations. Past that, the note says "Kept 300 of its operations; choose tags to narrow what is pulled". Pass
tags(at most 50) to keep only the operations with one of them. - The API is never called. Only its document is read. Its server address is kept as information.
{
"name": "orgs_integrations_apis_add",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"url": "https://api.example.com/openapi.json",
"title": "Billing API",
"idempotencyKey": "add-billing-api-2026-11-22"
}
} {
"integration": {
"id": "itg_01JX8C4D6E8F0G2H4J6K8M0N2P",
"kind": "openapi",
"url": "https://api.example.com/openapi.json",
"title": "Billing API",
"options": {},
"state": "ready",
"items": 1,
"tools": 48,
"blockedTools": 29,
"newTools": "allow",
…
},
"operations": 48,
"blocked": 29
} operations counts the tools it kept, and blocked how many of them start blocked.
A document behind sign-in
A URL that answers 401 or 403 needs a token. The first call without one is refused:
{
"error": {
"code": "validation",
"message": "The document's address asks for sign-in (HTTP 401): add a token to read it",
"details": {
"field": "token",
"needsToken": true,
"status": 401,
"next": "call again with token (used for this one read, never kept)"
}
}
} Call again with token. It goes in Authorization: Bearer <token> unless you name another header in tokenHeader, such as X-API-Key. A token that already starts with Bearer, Basic or Token is sent as it is.
{
"name": "orgs_integrations_apis_add",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"url": "https://internal.example.com/v2/openapi.yaml",
"token": "<token>",
"tokenHeader": "X-API-Key",
"tags": ["customers", "tickets"]
}
} The token is used for this one read and never kept. It is sent only to the document URL's own origin, never to an origin a redirect leads to. The audit records that a token was used, never the token. Because it isn't kept, a pull of this API always needs the token again.
An uploaded document needs no token, and a token with one is refused.
{
"name": "orgs_integrations_apis_add",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"document": "openapi: 3.1.0\ninfo:\n title: Tickets\n version: 1.4.0\npaths:\n …",
"fileName": "tickets.yaml"
}
} Read it again
orgs_integrations_apis_pull reads the document again: from its URL (with token again, if it needed one), or, for an upload, from the document you upload again. Operations found for the first time get the defaults above. Decisions already made stay.
{
"name": "orgs_integrations_apis_pull",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"integrationId": "itg_01JX8C4D6E8F0G2H4J6K8M0N2P",
"token": "<token>"
}
} An API pulled by orgs_integrations_sync is read again only when its document is public. Otherwise it is left as last pulled, with the note "Pull again needs your token" or "Uploaded: upload the document again to pull it again".
| Argument of orgs_integrations_apis_add | Type | Required | What it is |
|---|---|---|---|
orgId | string | yes | The organization (org_…). |
url | string | The OpenAPI document's https:// address. | |
document | string | Or the document itself, JSON or YAML (an upload), at most 5 MB. | |
fileName | string | An upload's file name, to know it by. | |
title | string | Its name (default: the document's title). | |
tags | string[] | Only the operations with one of these tags (an API of more than 300 operations is narrowed so). | |
token | string | Only if the url needs one: a bearer token, or the value of tokenHeader. Used for this one read and never kept. | |
tokenHeader | string | The header the token goes in, such as X-API-Key (default: Authorization: Bearer). | |
idempotencyKey | string | Any unique string: the call sent again with it answers its first result. |
Allow or block tools
Plans On Pro, Team, and Enterprise
Each tool of an integrated MCP server, and each operation of an API, is allowed or blocked for the organization's instructions. A blocked tool is never offered as people write, and an instruction that names one is marked.
List the tools
tools/call params{ "name": "orgs_integrations_tools_list", "arguments": { "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "query": "events" } }Answer{ "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "title": "Calendar", "newTools": "allow", "canBlock": true, "tools": [ { "name": "events.create", "description": "Create an event.", "state": "allowed", "foundAt": "2026-11-22T09:14:05.871Z" }, { "name": "events.delete", "description": "Delete an event.", "state": "allowed", "foundAt": "2026-11-22T09:14:05.871Z" }, { "name": "events.list", "description": "List events in a range.", "state": "allowed", "foundAt": "2026-11-22T09:14:05.871Z" } ] }The list comes 100 tools a page by default (
limitup to 300,cursorfor the next page).querynarrows it by words in a tool's name or description.include: ["inputSchema"]adds each tool's input schema, and an operation's output schema. A tool the server no longer lists keeps its decision and shows"present": false, after the others.canBlockis false on a plan without the badge above.Block a tool
Block events.delete{ "name": "orgs_integrations_tools_set", "arguments": { "orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "tools": ["events.delete"], "state": "blocked" } }Answer{ "integration": { "id": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M", "kind": "mcp", "title": "Calendar", "state": "ready", "tools": 12, "blockedTools": 1, "newTools": "allow", … }, "changed": true, "updated": 1 }updatedcounts the tools whose state changed. The same call again answers"changed": false:The same call again{ "integration": { … }, "changed": false, "updated": 0, "reason": "already so: nothing changed" }
What the call takes:
tools: 1 to 300 tool names, as the server lists them. A name the server never listed is refused withnot_found, itsdetails.toolsnaming the missing ones. Leavetoolsout to change every tool of the server.state:allowedorblocked. It is required when you nametools.newTools: what a tool found for the first time by a later pull gets.allow(the default) lets it be used at once;blockblocks it until someone allows it. For an API,allowstill blocks a new operation that isn't a read.
Give state, newTools or both. Changing newTools never changes the tools already known.
{
"name": "orgs_integrations_tools_set",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M",
"newTools": "block"
}
} {
"name": "orgs_integrations_tools_set",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"integrationId": "itg_01JX8A3B5C7D9E1F3G5H7J9K1M",
"state": "allowed"
}
} In the editor these are Allow, Block, Allow all and Block all on a server's tools, and New tools with New tools may be used at once or New tools wait until someone allows them. An API's page says New operations.
A plan without the badge above refuses orgs_integrations_tools_set with limit_reached, details.feature: "toolPolicy". Decisions made before a downgrade are kept, but on such a plan every tool counts as allowed: in the editor, in the marks and in the policy served with an instruction.
Only approved integrations
Plans On Team and Enterprise
With the policy key integrationsOnly on, an instruction's MCP servers, skills, agents and services are approved only when one of the organization's integrations offers them. Anything else is marked as not approved, and isn't used. The switch is Settings ▸ Integrations ▸ Only approved integrations, or:
{
"name": "orgs_policy_set",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"policy": { "integrationsOnly": true }
}
} A plan without the badge refuses true with limit_reached, details.feature: "integrationsOnly". The key is described with every other policy key on Organization policy.
An object is approved when every target it names (its src, endpoint, registry or server, normalized) is one an integration's item carries, or a registry integration's own address. Targets are compared normalized: scheme and host in lower case, default port and trailing slash dropped. To check some targets, ask orgs_integrations_search:
{
"name": "orgs_integrations_search",
"arguments": {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"targets": ["https://calendar.example.com/mcp", "https://tracker.example.com/mcp"],
"limit": 1
}
} {
"orgId": "org_01JX7Q2M4N8R5T6V9W0Y3Z1A2B",
"items": [ … ],
"approved": ["https://calendar.example.com/mcp"],
"blocked": { "https://calendar.example.com/mcp": ["events.delete"] },
"integrationsOnly": true
} approved lists the targets the integrations approve, and blocked the tools blocked on each. Up to 100 targets go in one call.
Where the decisions take effect
A decision is the organization's. It applies wherever an instruction is written, served or applied, each time from the organization's decisions at that moment. Versions are never changed.
- In the editor. A blocked tool is never offered in completions. An instruction that names one, or an object that isn't approved under the restriction, is marked: "This isn't one of your organization's approved integrations, so the agent won't use it."
- In the served text. Whatever serves a version (its
instruction://resource,instructions_versions_read, a read link, the page's Markdown) adds the organization's current policy for the targets the text names, ashost-integrationslines at the top of its front matter. The lines are outside the signed bytes. Their format, and how they combine with an author's ownintegrationskey, are on The integrations policy. instruction.md serves them. A self-hosted server serves them only withIMD_HOST_MATTER=on(the chart'sconfig.hostMatter: true); it is off by default. - When an agent's files are written.
instruction agents apply, its hooks and the runner askorgs_integrations_searchabout the targets the instruction names, when the instruction belongs to an organization the signed-in person or agent is a member of. A tool blocked on a server joins that server's deny list. Under the restriction, a server or a skill whose source isn't approved is skipped.
For Claude Code, a blocked tool becomes a deny rule in .claude/settings.json:
{
"permissions": {
"deny": ["mcp__calendar__events_delete"]
}
} For Codex, it goes in the server's disabled_tools:
# instruction.md apply: calendar
[mcp_servers.calendar]
url = "https://calendar.example.com/mcp"
disabled_tools = ["events.delete"] A skipped server is named in what apply prints:
acme/support-agent v4 for claude-code: servers calendar (not set up: tracker — the organization hasn't approved this server) What is already written into an agent's files stays until apply runs again for that instruction. Run instruction agents apply to take a new decision at once. apply blocks the tools the last pull knew of. When a server's new tools wait for review, a tool the server added after that pull is blocked only by a host that reads the served host-integrations lines, which say "default": "blocked". How apply works is on Servers, skills and accounts.
The policy says what the organization allows. It grants nothing: an agent still needs its own credentials for a server, and naming a tool gives no access to it. See Naming a tool never grants access.
Check it worked
orgs_integrations_listshows the integrationready, with theitemsandtoolsyou expect and no worryingnote.orgs_integrations_tools_listshows each tool with the state you set.orgs_integrations_searchwith the instruction's targets lists them underapproved, and the tools you blocked underblocked.- After
instruction agents apply, the deny rule is in.claude/settings.jsonordisabled_toolsin.codex/config.toml. - The audit trail records adding an integration (
integration.added), a change to its tools (integration.updated), an API read again (integration.updated) and removing one (integration.removed). A pull withorgs_integrations_sync, or adding the same one again, records nothing. TurningintegrationsOnlyon or off is anorg.updatedevent. See Audit trail.
Undo or stop
- Unblock a tool:
orgs_integrations_tools_setwith the sametoolsand"state": "allowed". - Stop reviewing new tools:
"newTools": "allow". - Lift the restriction:
orgs_policy_setwith{"integrationsOnly": false}, ornullto put the default back. - Remove an integration:
orgs_integrations_remove. Its tool decisions go with it.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
limit_reached: "integrations need the Pro plan or above" |
The organization's plan has no integrations | Upgrade the plan (details.upgrade names orgs_billing_checkout). |
limit_reached: "allowing and blocking tools needs the Pro plan or above" |
The plan lacks tool policy | Upgrade, or leave the tools as they are. |
validation: "a skills repository is on GitHub: https://github.com/owner/repository" |
A skills address that isn't a GitHub repository |
Give the repository's address, and its folder in path. |
validation: "url is an https:// address" |
Not https, a user name or password in it, or longer than 2,000 characters | Give the plain https address. |
State error, or a note such as "Couldn't list its tools: HTTP 404" |
The address doesn't answer as that kind, or isn't public | Check the address answers from the internet, then orgs_integrations_sync. |
| "The server asks for sign-in, so its tools aren't listed" | The MCP server needs credentials to list its tools | It is still approved by its address. Its tools can't be allowed or blocked one by one. |
not_found: "no such tool on this server (orgs_integrations_tools_list lists them)" |
A name in tools the server never listed |
Use the names orgs_integrations_tools_list gives, exactly. |
validation: "only an MCP server or an API has tools: …" |
integrationId is a registry, skills or agent |
Use the MCP server's or the API's integration. |
validation with details.needsToken: true |
The OpenAPI document's URL asks for sign-in, or refused the token | Call again with token (and tokenHeader if it isn't a bearer token). |
| "The document isn't an OpenAPI document: …", "The document lists no operations" | Not OpenAPI 3.0, 3.1 or Swagger 2.0, or no paths | Point at the OpenAPI document itself, not the API's own address. |
conflict: "this document is already another of the organization's APIs" |
An upload pulled again with a document another API already has | Pull the other API, or remove one. |
| Still stuck | Ask on Support. |
Questions
How do I allow only our approved MCP servers and block a tool?
Add each server with orgs_integrations_add, turn on integrationsOnly with orgs_policy_set, and block the tool with orgs_integrations_tools_set. Blocking is on the plans in Allow or block tools, and the restriction on those in Only approved integrations.
Does instruction.md call our API or our MCP server's tools?
No. It reads an OpenAPI document and lists an MCP server's tools, and nothing more. The tools are called by your agents, with their own credentials. See Import an API from its OpenAPI document.
Is the token for a private OpenAPI document kept?
No. It is used for that one read, sent only to the document's own origin, and never written anywhere. Each later pull asks for it again. See A document behind sign-in.
When does blocking a tool reach a running agent?
At once in the editor and in what instruction.md serves. In an agent's own files, when instruction agents apply runs again. See Where the decisions take effect.
What happens to blocked tools after a downgrade?
The decisions are kept, but on a plan without tool policy every tool counts as allowed. They apply again after an upgrade. See Allow or block tools.