Цю сторінку ще не перекладено.

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.

What a token reaches on the MCP server.

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.

Shell
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 401 with WWW-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, an Mcp-Session-Id header, or a 2025 protocol version) answers 400 with 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, HEAD and DELETE on the endpoint answer 405. Streams (subscriptions/listen, events/stream) are POST requests 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:

Server instructions
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.

ToolsetToolsWhat it holds
core7Orientation: who you are, finding tools, listing and reading instructions.
author23Creating instructions, their drafts, details, projects and folders.
spec8The language: validate, format, outline, fix, deliver, convert, explain.
review16Suggestions, comments and proposals.
versions11Releases, refs, versions and diffs.
automation4Schedules and release checks.
distribution1Exports.
share17Visibility, access, read links, forks, transfers and sealed workspaces' keys.
consume26Bindings, consumers, deployments and conversations with agents.
org73Organizations: members, invitations, workspaces, policy, integrations, people, sign-in, domains, apps, keys, agent credentials.
account19Your own account: profile, preferences, connected apps, export, deletion.
insights4Activity, audit and usage.
billing3Checkout, the billing portal and the spending limit.
live1The editor's presence.
system8instruction.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:

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.

BucketCalls a minuteBurstToolsWhat counts
person-search30101Search by meaning (instructions_search), which spends the embedding model's time.
person-live9001202The editor's live tools: the draft's sync and presence.
person-writes12040145Tools that change something.
person-reads60012073Tools 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.

Shell
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":{}}}}'
Its answer (structuredContent), shortened
{
  "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.view says 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 with ci- or names GitHub), agent-writer (an agent whose credential has instructions:write, :publish or :admin), consumer (any other agent), system (instruction.md's own services) or anonymous.
  • me.scopes lists only the token's instructions:* and org:* scopes.
  • skills depends on the view: a following agent is pointed at following-instructions, a CI caller also at release-gates-in-ci.
  • orgs[].web and an instruction's web are the addresses on the site. Link to them; don't build them.

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.

tools/call params
{"name":"capabilities_search","arguments":{"query":"roll back a release","limit":3}}
Its answer (structuredContent) for a person in an AI app
{
  "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

Last checked against the product:

Was this page helpful? Report a problem