Cette page n’est pas encore traduite.

Sign-in, scopes and tokens

This page is for developers who connect a host, an agent or their own code to the MCP server. It gives the sign-in endpoints, the grants each kind of caller uses, how long tokens last, and which tools each scope opens.

Every caller signs in

The server at https://instruction.md/mcp answers nothing without a valid bearer token. A request with no token, whatever its method, answers HTTP 401 before any MCP work. The WWW-Authenticate challenge names the protected-resource metadata, which is where a host following the MCP authorization spec starts:

Protected-resource metadata
curl -s https://instruction.md/.well-known/oauth-protected-resource/mcp
The answer (abridged)
{
  "resource": "https://instruction.md/mcp",
  "authorization_servers": [
    "https://instruction.md/auth/realms/instruction-md"
  ],
  "scopes_supported": [
    "openid",
    "profile",
    "email"
  ],
  …
}

The metadata names one authorization server, the people's sign-in, https://instruction.md/auth/realms/instruction-md. Its OpenID Connect discovery gives the endpoints:

Discovery
curl -s https://instruction.md/auth/realms/instruction-md/.well-known/openid-configuration \
  | jq '{issuer, authorization_endpoint, token_endpoint, device_authorization_endpoint}'
The endpoints
{
  "issuer": "https://instruction.md/auth/realms/instruction-md",
  "authorization_endpoint": "https://instruction.md/auth/realms/instruction-md/protocol/openid-connect/auth",
  "token_endpoint": "https://instruction.md/auth/realms/instruction-md/protocol/openid-connect/token",
  "device_authorization_endpoint": "https://instruction.md/auth/realms/instruction-md/protocol/openid-connect/auth/device"
}

What the server accepts

Check Value
Issuers https://instruction.md/auth/realms/instruction-md, https://instruction.md/auth/realms/instruction-md-agents
Audience https://instruction.md/mcp. Every token instruction.md issues for the server carries it; you don't ask for it.
Signature RS256, checked against each issuer's published keys
Clock skew 60 seconds
Scopes read from the scope claim and the imd_scopes claim

A token that doesn't verify answers 401 with error="invalid_token". The well-known metadata and /health need no token.

People in a host

A person who adds instruction.md to Claude, ChatGPT, Claude Code or VS Code signs in through the host with OAuth: the authorization code grant with PKCE (S256 only), and a consent screen the first time a host connects. The host signs in as the person and acts as them, limited to what they allow (below).

How the host identifies itself:

  • Client ID metadata documents. A host whose client ID is the URL of its metadata document signs in with that URL. Claude's documents on claude.ai are fetched and checked. ChatGPT's, Claude Code's, VS Code's and Claude's confidential client are registered by their URLs ahead of time and never fetched.
  • A client ID you paste. A host that lets you type a client ID, such as Claude's advanced settings, can use mcp-hosts: a public client with no secret. It accepts only the callbacks of Claude (claude.ai and claude.com) and ChatGPT.
  • Dynamic client registration is off. An anonymous registration answers 403. A host that only registers itself can't connect; use a host that supports client ID metadata documents, or paste mcp-hosts.

The clients of Claude Code and VS Code redirect to a loopback address on the person's machine (VS Code also through https://vscode.dev/redirect, which hands the code to the VS Code on that machine). Any process on that machine can answer such a redirect, so these two clients can never be given org:admin.

The CLI

The instruction CLI signs in as the person with its own public client, instruction-cli:

Shell
instruction login                 # a browser on this machine: the everyday tools
instruction login --device        # a code to type on another device (SSH, a container)
instruction login --admin         # also org:admin
instruction whoami --json         # who the server says you are, with the token's scopes
  • The browser (default): the authorization code with PKCE, back to http://127.0.0.1/callback on a port the CLI opens for that one sign-in.
  • --device: the device authorization grant, with PKCE. The code lasts 5 minutes; the CLI polls every 5 seconds.
  • --admin: asks for org:admin as well. A command that needs it (instruction keys and instruction agents other than list, and instruction audit) offers on a terminal to sign in again with it. Without a terminal it stops and says to run instruction login --admin.

The sign-in is kept in ~/.config/instruction-md/credentials.json ($XDG_CONFIG_HOME/instruction-md/ when that is set; mode 0600), and is sent only to the server it was issued for. instruction mcp and instruction agents use the same sign-in. --token or INSTRUCTION_MD_TOKEN passes a token as it is, never refreshed. See Environment variables and files.

The editor

The editor's own client is first party. Its tokens carry org:admin by default and no instructions:* scope, so the person's role alone decides what it may do.

Agents and services

An agent or a service has a credential of its own: a confidential client in a separate realm, issued by an organization admin under Developer ▸ API keys or with instruction agents create. It uses the client credentials grant at the agents' token endpoint, which the protected-resource metadata doesn't name:

A client-credentials token request
curl -s -X POST 'https://instruction.md/auth/realms/instruction-md-agents/protocol/openid-connect/token' \
  -d grant_type=client_credentials \
  -d client_id='agt_<…>' \
  -d client_secret="$INSTRUCTION_MD_CLIENT_SECRET"
The answer
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "expires_in": 300,
  "token_type": "Bearer",
  …
}
The agents' discovery
curl -s https://instruction.md/auth/realms/instruction-md-agents/.well-known/openid-configuration | jq .token_endpoint

The request needs no scope and no audience: both are fixed on the client. The token names the agent, its organization and its scopes:

The claims the server reads
{
  "iss": "https://instruction.md/auth/realms/instruction-md-agents",
  "aud": "https://instruction.md/mcp",
  "azp": "agt_<…>",
  "actor_type": "agent",
  "client_id": "agt_<…>",
  "org_id": "org_<…>",
  "imd_scopes": "instructions:read instructions:write",
  "exp": …
}

Creating, rotating and revoking a credential, and using its token in CI, are on Agent credentials and CI tokens.

Plans Pro 10 · Team 100 · Enterprise unlimited

Apps

Token lifetimes

Token Lifetime
A person's access token (host, CLI, editor) 5 minutes
A person's refresh token As long as the sign-in session: 30 days without use, 90 days at most
An agent's or a service's access token 5 minutes (expires_in: 300). No refresh token: ask for a new one
The CLI's device code 5 minutes
A revoked agent's tokens Refused at once: a call answers forbidden ("this agent credential is not one of ours, or was revoked"). It gets no new ones

Hosts refresh their own tokens. To refresh by hand, send the refresh token to the people's token endpoint with the client ID it was issued to, and the server as the resource:

Refresh a person's token
curl -s -X POST 'https://instruction.md/auth/realms/instruction-md/protocol/openid-connect/token' \
  -d grant_type=refresh_token \
  -d client_id=instruction-cli \
  -d refresh_token="$REFRESH_TOKEN" \
  -d resource=https://instruction.md/mcp

Each refresh answers a new refresh token. Store it in place of the old one. The CLI refreshes a stored sign-in 30 seconds before its access token lapses, and once more after a 401, so a long-running instruction watch or instruction mcp keeps working.

What a person lets a host do

When a person connects a host, the sign-in asks What may Claude do? (with the app's name). Each choice includes the one before, and Follow changes live is a separate switch. The first connection offers Read, write and publish with Follow changes live on. The choice becomes scopes on the host's token:

ChoiceScopeTools that need it (hostNeeds)
Read onlyinstructions:readnothing more: 56 tools, such as session_bootstrap, capabilities_search, instructions_list
Read and write draftsinstructions:writewrite: 38 tools, such as instructions_create, instructions_draft_replace, instructions_draft_edit
Read, write and publishinstructions:publishpublish: 11 tools, such as instructions_proposals_merge, instructions_publish, instructions_refs_set
Everything you can doinstructions:adminadmin: 89 tools, such as instructions_rename, instructions_archive, instructions_delete
Follow changes liveinstructions:followfollow: 6 tools, such as instructions_bindings_create, instructions_bindings_delete, instructions_bindings_report

A tool's need comes from its class in the registry: an edit-class tool needs write, a publish-class tool publish, and an admin-class tool admin. A read-class tool that changes something needs write (follow for the tools named below, admin for revoking an app and deleting the account), apart from a few that change only the caller's own view (exporting, marking a notice read). The tools that need follow are instructions_bindings_create, instructions_bindings_delete, instructions_bindings_report, deployments_report, deployments_asks_create, deployments_asks_withdraw.

A host's token lists and calls only the tools its scopes allow. A call it isn't allowed answers scope_required, naming the scope:

A host asked for more than the person allowed
{
  "error": {
    "code": "scope_required",
    "message": "the person connected this app with less access than this needs: they can allow more in instruction.md, Settings, Connected apps",
    "details": {
      "scope": "instructions:publish",
      "next": "Tell the person: open instruction.md, Settings, Connected apps, and allow this app to do more."
    }
  }
}

The person changes the choice under Your account ▸ Connected apps. It takes effect within a few minutes. A person's token with no instructions:read scope (the editor's, and a host connected before the choice existed) is not limited this way.

Scopes never widen what the person may do. Each call still checks the person's role on the instruction, workspace or organization, and a tool that asks to confirm still asks.

org:admin

Administering an organization takes the scope org:admin. Without it a token doesn't list the 61 admin tools of the org, billing and insights toolsets (57 apart from instruction.md staff's own admin_* tools). With it, the person's role decides: only an organization's owners and admins change it, and its billing members its billing.

  • The server never names org:admin in its metadata or its 401 challenge (openid, profile, email only), so a host that asks for what the challenge names gets the everyday tools.
  • A host gets it only when it asks for it by name and the person agrees. The consent screen then says "Administer your organizations on instruction.md: members, invitations, workspaces, policy, keys, agents, billing and audit".
  • A limited host keeps it only when the person chose Everything you can do.
  • A host that named its scopes when it first connected, without org:admin, is refused a later sign-in that asks for it (invalid_scope). Remove the connector and add it again, naming org:admin.
  • The clients of Claude Code and VS Code can't have it. Use the editor's Settings, or the CLI with instruction login --admin.
  • No agent or service credential can have it.
The 61 tools that need org:admin
ToolTitleToolset
orgs_createCreate an organizationorg
orgs_renameRename an organizationorg
orgs_deleteDelete an organizationorg
orgs_members_addAdd a memberorg
orgs_members_updateChange a member's roleorg
orgs_members_removeRemove a memberorg
orgs_invitations_createInvite someoneorg
orgs_invitations_listList pending invitationsorg
orgs_invitations_revokeRevoke an invitationorg
orgs_workspaces_createCreate a workspaceorg
orgs_workspaces_updateChange a workspaceorg
orgs_workspaces_deleteDelete a workspaceorg
orgs_workspaces_roles_setSet a workspace roleorg
orgs_policy_getGet an organization's policyorg
orgs_policy_setChange policyorg
orgs_integrations_addAdd an integrationorg
orgs_integrations_syncPull an integration againorg
orgs_integrations_removeRemove an integrationorg
orgs_integrations_tools_setAllow or block an MCP server's toolsorg
orgs_integrations_apis_addAdd an APIorg
orgs_integrations_apis_pullRead an API's document againorg
orgs_people_directories_addAdd a people directoryorg
orgs_people_directories_pullPull a people directory againorg
orgs_people_directories_setOffer or hide a directory's peopleorg
orgs_scim_tokens_listList SCIM tokensorg
orgs_scim_tokens_createMake or rotate a SCIM tokenorg
orgs_scim_tokens_revokeRevoke a SCIM tokenorg
orgs_signin_getSee your organization's sign-inorg
orgs_signin_provider_saveSet up your identity providerorg
orgs_signin_provider_removeRemove your identity providerorg
orgs_signin_domains_addAdd an email domainorg
orgs_signin_domains_verifyVerify an email domainorg
orgs_signin_domains_removeRemove an email domainorg
orgs_signin_setTurn your sign-in on or offorg
orgs_keys_addAdd your own keyorg
orgs_keys_rotateRotate the platform keyorg
orgs_keys_retireRetire a keyorg
orgs_keys_revokeRevoke a keyorg
orgs_agents_createConnect an agentorg
orgs_agents_rotateRotate an agent's secretorg
orgs_agents_revokeRevoke an agentorg
orgs_apps_createRegister an apporg
orgs_apps_updateChange an apporg
orgs_apps_rotateGive an app a new client idorg
orgs_apps_revokeRevoke an apporg
orgs_apps_review_requestAsk for sensitive scopesorg
orgs_domains_addAdd a domainorg
orgs_domains_verifyVerify a domainorg
orgs_domains_removeRemove a domainorg
orgs_apps_policy_getSee the apps your people useorg
orgs_apps_policy_setAllow or block appsorg
admin_apps_reviews_list (staff)List app reviewsorg
admin_staff_list (staff)List instruction.md's stafforg
admin_staff_set (staff)Change instruction.md's stafforg
admin_apps_review (staff)Decide an app revieworg
instructions_activity_listList recent activityinsights
instructions_audit_queryQuery the audit trailinsights
instructions_audit_exportExport the auditinsights
orgs_billing_checkoutUpgrade the planbilling
orgs_billing_portalOpen the billing portalbilling
orgs_spending_setSet the spending limitbilling

What agents can't do

An agent's or a service's scopes are instructions:read, instructions:write and instructions:publish. They stop at publish:

  • No admin-class tools. The 91 admin-class tools are for people only. They are hidden from agent and service tokens, and the server refuses them on every call. They cover sharing and visibility, deleting and revoking, deployment rules and answering agents, and the organization's members, workspaces, policy, keys, credentials, billing and audit.
  • Publish needs the policy too. An organization doesn't let agents publish until an admin turns on Agents may publish in Settings ▸ Security. See Organization policy, roles and permissions.
  • A narrower scope answers scope_required, with the scope the call would need in details.scope.

Two more groups are out of every caller's reach: 8 system tools for instruction.md's own services, and 13 tools only the editor calls (such as instructions_draft_sync and instructions_presence_set). Neither is listed to a host or an agent.

If it doesn't work

What you see Why What to do
HTTP 401 with resource_metadata No token Sign in: let the host follow the challenge, or run instruction login
HTTP 401 with error="invalid_token" Expired, for another audience, or from another issuer Refresh, or ask for a new token from the right token endpoint
HTTP 403 on client registration Dynamic client registration is off Use a host with client ID metadata documents, or paste the client ID mcp-hosts
invalid_scope at sign-in The host's client lacks a scope it asked for, usually org:admin Remove the connector and add it again, naming org:admin; or use the CLI with --admin
The organization tools aren't listed The token has no org:admin See org:admin
scope_required The person limited the host, or the agent's credential is narrower Allow more under Your account ▸ Connected apps, or issue a credential with the scope
Still stuck Send a request

Generated from the code

The issuers, audiences and metadata on this page are read from the gateway's generated configuration (deploy/mcpg/prod.yaml), and the tool counts and lists from the tool registry (packages/registry/registry.json), when the docs are built.

Last checked against the product:

Was this page helpful? Report a problem