The MCP server
For developers writing or configuring an MCP client: where the server is, the one protocol version it speaks, which of its 221 tools a given token is shown, and the two calls a client makes first. Connecting a particular host is Connect an MCP client.
Endpoint and protocol
The server is one endpoint, https://instruction.md/mcp. It is an MCP gateway in front of instruction.md's database and services, and it names itself instruction.md ("Instructions for AI agents: write, review, release and follow versioned, signed instructions.").
| Endpoint | https://instruction.md/mcp, POST only |
| Protocol version | 2026-07-28, and no other |
| Sessions | None. There is no initialize and no Mcp-Session-Id |
| Sign-in | Required for every request, discovery and every */list included |
| Authorization server | https://instruction.md/auth/realms/instruction-md |
| Protected-resource metadata | https://instruction.md/.well-known/oauth-protected-resource/mcp |
| Server card | GET https://instruction.md/mcp/server-card |
The server speaks MCP 2026-07-28, the stateless protocol. Every request carries the protocol version, the client's name and version, and its capabilities in params._meta. The Mcp-Protocol-Version, Mcp-Method and Mcp-Name headers repeat what the body says. With no session, any replica of the gateway answers any request.
curl -s https://instruction.md/mcp \
-H 'authorization: Bearer <access token>' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'mcp-protocol-version: 2026-07-28' \
-H 'mcp-method: server/discover' \
-d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientInfo":{"name":"my-client","version":"1.0.0"},
"io.modelcontextprotocol/clientCapabilities":{}}}}' What the server refuses at the door:
- A request without a valid token answers
401withWWW-Authenticate: Bearer resource_metadata="…", before any MCP work. A host that follows the MCP authorization spec starts its sign-in from there. See Sign-in, scopes and tokens. - The session wire (
initialize, anMcp-Session-Idheader, or a 2025 protocol version) answers400with the JSON-RPC error-32022. A host that only speaks an older MCP connects through the CLI's stdio server instead: see instruction-mcp and Connect an MCP client. GET,HEADandDELETEon the endpoint answer405. Streams (subscriptions/listen,events/stream) arePOSTrequests whose answer is a server-sent event stream.
Server instructions
The server sends hosts this text, which a host gives its model before the first call. It is the short version of this reference:
instruction.md keeps instructions for AI agents: Markdown documents whose MUST, SHOULD and NEVER lines are binding,
versioned, signed, and served over MCP, so every agent follows the version its people released. You can write, review,
release, share and follow instructions here, as the person who connected you.
Start with `session_bootstrap`: it says who you act for, their organizations and workspaces, what you may do, and what
to read next. If a tool you need isn't listed, `capabilities_search` finds it.
Tool families:
- `instructions_*`, the work itself: `instructions_list` and `instructions_search` find, `instructions_get` reads (with
`include: ["draft"]` the draft's text and revision), `instructions_create` starts one.
- Drafts: `instructions_draft_edit` makes precise edits (pass the draft's revision as `expectedRevision`),
`instructions_draft_replace` sets a whole text. A contributor's or an agent's edits land as suggestions a maintainer
accepts (`instructions_suggestions_accept`); comments are `instructions_comments_*`.
- Checking: `instructions_validate` checks a stored draft with the reader a release uses; `spec_validate`, `spec_fixes`
and `spec_outline` work on any text.
- Releasing: `instructions_publish` makes the next version, and agents following `latest` switch to it, so it asks first
(below). `instructions_versions_list`, `instructions_versions_read` and `instructions_diff` read the past;
`instructions_refs_set` moves a ref such as `stable`.
- Sharing: `instructions_access_*`, `instructions_visibility_set`, `instructions_links_*` (a signed read link).
- Following: an agent declares what it follows with `instructions_bindings_create` and reports what it applied, and in
which app (`host`: claude-code, codex…), with `instructions_bindings_report`. To take an instruction as this
conversation's own instructions, use the prompt `follow`.
- `orgs_*` run an organization: members, workspaces, invitations, policy, signing keys, agents, billing. They need the
OAuth scope `org:admin`; without it they aren't listed.
The confirm contract: a tool that changes what others receive, or can't be undone, answers its first call with the
error `needs_confirmation` (a `summary`, its `consequences`, a `confirmToken`, the step `next`). Show the person the
summary and consequences; only if they agree, call again with the same arguments plus `confirmToken` (10 minutes,
once). Never confirm on the person's behalf.
Sending a call again is safe: a create takes an `idempotencyKey`, an edit with the same `expectedRevision` answers what
it did, and asking for what already holds answers `changed: false`. Lists answer a page at a time (`nextCursor` back as
`cursor`); `detail: "full"` asks for whole items.
Errors carry a `code` (`validation`, `not_found`, `forbidden`, `conflict`, `version_conflict`, `limit_reached`,
`needs_confirmation`, `unavailable`), a message, and `details`: the argument at fault (`field`) and the next step
(`next`). On `version_conflict`, read again (`reread`) and redo your change on what you read.
Live updates (a subscription to an instruction, the events `md.instruction.activity` and `md.instruction.releases`) go
to one agent or app at a time on a Community workspace; a second is refused `limit_reached` with `retryAfterSeconds`.
Reading is never limited.
Reading: an instruction is a resource, `instruction://{owner}/{name}` (its default ref's version), `@stable` or `@v3`
for one, and `instruction://{id}/draft`; without resources, `instructions_get` with `include: ["draft"]` and
`instructions_versions_read` give the same texts. The skills at `skill://instruction-md/index.json` explain common
tasks; load the one that fits before a larger task. What a token is shown
A tool the gateway won't let a caller call is not in that caller's tools/list, and session_bootstrap and capabilities_search name only what is listed. So two clients of the same server can see different lists. Being listed authorizes nothing by itself: the server checks the caller's role on the instruction or organization at every call.
| Who calls | What is listed |
|---|---|
| Nobody signed in | Nothing: the request answers 401 |
| A person, in an AI app or the CLI | Every tool for people and agents, and the people-only tools (class admin). The organization's administration tools only with the scope org:admin |
| A person who limited the AI app at sign-in | The tools that need no scope (most reads, and the two exports), and each other tool only when the app was allowed the scope it needs (below) |
| An agent with an agent credential | The tools for people and agents. Never a people-only tool, so never the organization's administration |
| instruction.md's own apps and services | Also the tools marked "not callable by customers" in the Tool reference |
Of the 221 tools, 113 are for people and agents, 83 for people only, 4 for instruction.md's staff, 13 for instruction.md's own apps and 8 for its own services.
The organization's tools. The 61 people-only tools of the org, billing and insights toolsets (57 of them, without the staff's own admin_* tools) are listed only to a token that carries org:admin. The server never names that scope in its 401 challenge or its metadata, so a host signs in for the everyday tools. The editor and instruction login --admin ask for it. Sign-in, scopes and tokens says how a host can.
A limited AI app. When a person connects an AI app, they choose what it may do. The app's token then carries instructions:read and the scopes for what they allowed. A tool that names one of the four scopes below is listed only when the token carries it. Every tool that changes something names one, but instructions_export and me_export, and so do a few reads that only an Admin may make (such as instructions_access_list and instructions_consumers_list):
| Scope | Tools that need it | What it allows |
|---|---|---|
instructions:write |
40 | Create, duplicate and fork instructions; edit drafts and details; projects, folders and favorites; suggestions, comments and proposals; ask for access; accept an invitation; your profile and preferences; sealed workspaces' keys and drafts |
instructions:publish |
11 | Release versions, merge proposals, move and delete refs, schedules, release checks, signed read links |
instructions:admin |
94 | Rename, archive, delete, purge and transfer; visibility and access; revoke versions; pause bindings and list consumers; deployments and their conversations; the organization's administration; your connected apps and deleting your account |
instructions:follow |
6 | Follow an instruction (bindings) and report what was applied; a runner's reports; an agent's questions to its people |
A token without instructions:read is not limited by this rule. Agents' scopes are set on their credential: see Agent credentials.
Toolsets
Each tool belongs to one toolset. session_bootstrap answers the toolsets the caller's list holds.
| Toolset | Tools | What it holds |
|---|---|---|
core | 7 | Orientation: who you are, finding tools, listing and reading instructions. |
author | 23 | Creating instructions, their drafts, details, projects and folders. |
spec | 8 | The language: validate, format, outline, fix, deliver, convert, explain. |
review | 16 | Suggestions, comments and proposals. |
versions | 11 | Releases, refs, versions and diffs. |
automation | 4 | Schedules and release checks. |
distribution | 1 | Exports. |
share | 17 | Visibility, access, read links, forks, transfers and sealed workspaces' keys. |
consume | 26 | Bindings, consumers, deployments and conversations with agents. |
org | 73 | Organizations: members, invitations, workspaces, policy, integrations, people, sign-in, domains, apps, keys, agent credentials. |
account | 19 | Your own account: profile, preferences, connected apps, export, deletion. |
insights | 4 | Activity, audit and usage. |
billing | 3 | Checkout, the billing portal and the spending limit. |
live | 1 | The editor's presence. |
system | 8 | instruction.md's own services. |
Hints a host reads
Every tool carries the four MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), worked out from what it does. They are hints for the host, never authorization. Some hosts read more:
- Loaded up front. Claude Code loads these tools before its tool search:
session_bootstrap,capabilities_search,instructions_list,instructions_get,instructions_draft_edit. - The person makes the call. Claude Code asks the person before each of these, in every mode, because they can't be undone:
instructions_purge,instructions_versions_revoke,orgs_delete,orgs_keys_revoke,orgs_agents_rotate,orgs_agents_revoke,me_delete. The server's own confirmation still applies. - Status lines. The tools most used in conversation say what ChatGPT shows while they run and once they have.
- Large answers. A tool whose answer can be a long text raises Claude Code's limit for keeping it in the conversation.
39 tools ask for confirmation first: their first call answers needs_confirmation, and nothing changes until the person agrees. See Contracts.
Rate limits
The gateway counts each person's calls per minute, in one bucket by what the call costs, across every replica. Past a bucket's rate and burst, the call is refused and the caller waits.
| Bucket | Calls a minute | Burst | Tools | What counts |
|---|---|---|---|---|
person-search | 30 | 10 | 1 | Search by meaning (instructions_search), which spends the embedding model's time. |
person-live | 900 | 120 | 2 | The editor's live tools: the draft's sync and presence. |
person-writes | 120 | 40 | 145 | Tools that change something. |
person-reads | 600 | 120 | 73 | Tools that change nothing, and every resource read. |
A person also has at most 4 calls in flight that need instruction.md's services (the language reader, checks, diffs, the draft). A further call waits its turn for up to 20 seconds.
Where a client starts
session_bootstrap
Call session_bootstrap first. It changes nothing and answers who the token acts for, the organizations and workspaces with the caller's role and plan in each, the toolsets the caller's list holds, the skills to load first, the unread notifications and what to do next.
curl -s https://instruction.md/mcp \
-H 'authorization: Bearer <access token>' \
-H 'content-type: application/json' \
-H 'accept: application/json, text/event-stream' \
-H 'mcp-protocol-version: 2026-07-28' \
-H 'mcp-method: tools/call' \
-H 'mcp-name: session_bootstrap' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"session_bootstrap","arguments":{},"_meta":{
"io.modelcontextprotocol/protocolVersion":"2026-07-28",
"io.modelcontextprotocol/clientInfo":{"name":"my-client","version":"1.0.0"},
"io.modelcontextprotocol/clientCapabilities":{}}}}' {
"server": { "kind": "remote", "name": "instruction.md", "mcp": "https://instruction.md/mcp", "web": "https://instruction.md" },
"me": {
"id": "usr_<…>", "kind": "user", "name": "Maria Lopez", "handle": "maria",
"email": "maria@acme.example", "emailVerified": true, "view": "host",
"scopes": [], "personalOrg": "org_<…>"
},
"orgs": [
{
"id": "org_<…>", "slug": "acme", "name": "Acme", "type": "team", "role": "admin", "plan": "team",
"web": { "home": "https://instruction.md/acme", "drive": "https://instruction.md/acme/-/instructions", "settings": "https://instruction.md/acme/-/settings" },
"memberDefaults": { "developerMode": true },
"workspaces": [
{ "id": "ws_<…>", "slug": "main", "name": "Main", "role": "admin", "isDefault": true, "restricted": false, "instructions": 12 }
]
}
],
"toolsets": ["account", "author", "consume", "core", "distribution", "review", "share", "spec", "versions", "…"],
"skills": [
"skill://instruction-md/instruction-md-basics/SKILL.md",
"skill://instruction-md/writing-instructions/SKILL.md",
"skill://instruction-md/improving-an-instruction/SKILL.md",
"skill://instruction-md/releasing-and-rolling-back/SKILL.md"
],
"extension": { "id": "md.instruction/extension", "version": "0.2", "index": "instruction://index.json", "skills": "skill://instruction-md/index.json" },
"unread": 3,
"instructions": "instruction.md keeps instructions for AI agents: … Load `skill://instruction-md/instruction-md-basics/SKILL.md` before your first change.",
"next": ["instructions_list to see what exists; instructions_create to start one; read skill://instruction-md/index.json for how-tos."]
} me.viewsays how the server sees the caller, from its token and never from what the client says:host(a person in an AI app or the CLI),first-party(a person in instruction.md's own apps, such as the editor),app(a person through an app that uses Sign in with instruction.md, which is not available yet),ci(a service whose client id starts withci-or names GitHub),agent-writer(an agent whose credential hasinstructions:write,:publishor:admin),consumer(any other agent),system(instruction.md's own services) oranonymous.me.scopeslists only the token'sinstructions:*andorg:*scopes.skillsdepends on the view: a following agent is pointed atfollowing-instructions, a CI caller also atrelease-gates-in-ci.orgs[].weband an instruction'swebare the addresses on the site. Link to them; don't build them.
capabilities_search
When the tool a task needs isn't in the list, ask capabilities_search in words. It matches the names, titles and descriptions of the tools, resources, prompts and skills the caller is listed, and returns 10 by default (limit, 50 at most). Each word of two letters or more counts 3 when it is in a name and 1 when it is only in the title or description. A few words also search for the server's own terms: "roll back" adds refs, latest, restore and rollback, "share" adds visibility and access, "release" adds publish and version. The best scores come first. A query with no word to match answers validation on query.
{"name":"capabilities_search","arguments":{"query":"roll back a release","limit":3}} {
"matches": [
{
"kind": "tool",
"name": "instructions_publish",
"title": "Release a version",
"use": "Release the draft's accepted text as the next version (v1, v2 …) with a message",
"toolset": "versions",
"score": 9
},
{
"kind": "skill",
"name": "skill://instruction-md/releasing-and-rolling-back/SKILL.md",
"title": "releasing-and-rolling-back",
"use": "Release a new version of an instruction to the agents that follow it, roll back to an earlier version, move a ref such as stable, or revoke a harmful version — \"ship it\", \"publish the changes\", \"roll back to v6\", \"promote to stable\", \"v5 leaked a key, kill it\"",
"score": 9
},
{
"kind": "tool",
"name": "instructions_refs_set",
"title": "Point a ref at a version",
"use": "Point a ref (latest by default, or stable, beta…) at a version, rolling back included; with makeDefault the ref also becomes the one readers get when they name none; policy replaces its gates: signed versions only, passed checks, who may move it, a timed promotion from another ref",
"toolset": "versions",
"score": 8
}
]
} What the server offers
| How many | Reference | |
|---|---|---|
| Tools | 221 (196 callable by customers) | Tool reference |
| Resources and resource templates | 35 | Resources and addresses |
| Prompts | 16 | Prompts and skills |
| Skills | 11 | Prompts and skills |
| MCP Events types | 4 | Live updates, events and webhooks |
| MCP Apps | 3 | MCP Apps |
The rules every tool follows (confirmation, idempotency keys, expected revisions, paging, output schemas) are on Contracts, and every error code is on Errors.
The gateway also has one tool of its own, realtime_admit, which it calls to decide who may hold live updates. It is never listed and a client can't call it.
If it doesn't work
| What you see | Why | What to do |
|---|---|---|
401 and WWW-Authenticate: Bearer resource_metadata=… |
The request had no token, or one the server doesn't accept | Sign in through the authorization server the metadata names. See Sign-in, scopes and tokens |
400 with error -32022 |
The client speaks the session wire or a 2025 protocol version | Use a client that speaks 2026-07-28, or the CLI's stdio server (instruction-mcp) |
An organization's administration tool (such as orgs_members_add) is missing from the list |
The token has no org:admin, or it is an agent's |
Sign in again asking for org:admin (people only). See Sign-in, scopes and tokens |
| A changing tool is missing in an AI app | The person limited the app when they connected it | They change it under Your account ▸ Connected apps |
| A call is refused right after many others | A rate-limit bucket is spent | Wait and send it again; see Rate limits |
| Still stuck | Troubleshooting, or ask us |