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:
curl -s https://instruction.md/.well-known/oauth-protected-resource/mcp {
"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:
curl -s https://instruction.md/auth/realms/instruction-md/.well-known/openid-configuration \
| jq '{issuer, authorization_endpoint, token_endpoint, device_authorization_endpoint}' {
"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:
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/callbackon 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 fororg:adminas well. A command that needs it (instruction keysandinstruction agentsother thanlist, andinstruction audit) offers on a terminal to sign in again with it. Without a terminal it stops and says to runinstruction 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:
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" {
"access_token": "eyJhbGciOiJSUzI1NiIs…",
"expires_in": 300,
"token_type": "Bearer",
…
} 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:
{
"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:
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:
| Choice | Scope | Tools that need it (hostNeeds) |
|---|---|---|
| Read only | instructions:read | nothing more: 56 tools, such as session_bootstrap, capabilities_search, instructions_list |
| Read and write drafts | instructions:write | write: 38 tools, such as instructions_create, instructions_draft_replace, instructions_draft_edit |
| Read, write and publish | instructions:publish | publish: 11 tools, such as instructions_proposals_merge, instructions_publish, instructions_refs_set |
| Everything you can do | instructions:admin | admin: 89 tools, such as instructions_rename, instructions_archive, instructions_delete |
| Follow changes live | instructions:follow | follow: 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:
{
"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:adminin its metadata or its 401 challenge (openid,profile,emailonly), 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, namingorg: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
| Tool | Title | Toolset |
|---|---|---|
orgs_create | Create an organization | org |
orgs_rename | Rename an organization | org |
orgs_delete | Delete an organization | org |
orgs_members_add | Add a member | org |
orgs_members_update | Change a member's role | org |
orgs_members_remove | Remove a member | org |
orgs_invitations_create | Invite someone | org |
orgs_invitations_list | List pending invitations | org |
orgs_invitations_revoke | Revoke an invitation | org |
orgs_workspaces_create | Create a workspace | org |
orgs_workspaces_update | Change a workspace | org |
orgs_workspaces_delete | Delete a workspace | org |
orgs_workspaces_roles_set | Set a workspace role | org |
orgs_policy_get | Get an organization's policy | org |
orgs_policy_set | Change policy | org |
orgs_integrations_add | Add an integration | org |
orgs_integrations_sync | Pull an integration again | org |
orgs_integrations_remove | Remove an integration | org |
orgs_integrations_tools_set | Allow or block an MCP server's tools | org |
orgs_integrations_apis_add | Add an API | org |
orgs_integrations_apis_pull | Read an API's document again | org |
orgs_people_directories_add | Add a people directory | org |
orgs_people_directories_pull | Pull a people directory again | org |
orgs_people_directories_set | Offer or hide a directory's people | org |
orgs_scim_tokens_list | List SCIM tokens | org |
orgs_scim_tokens_create | Make or rotate a SCIM token | org |
orgs_scim_tokens_revoke | Revoke a SCIM token | org |
orgs_signin_get | See your organization's sign-in | org |
orgs_signin_provider_save | Set up your identity provider | org |
orgs_signin_provider_remove | Remove your identity provider | org |
orgs_signin_domains_add | Add an email domain | org |
orgs_signin_domains_verify | Verify an email domain | org |
orgs_signin_domains_remove | Remove an email domain | org |
orgs_signin_set | Turn your sign-in on or off | org |
orgs_keys_add | Add your own key | org |
orgs_keys_rotate | Rotate the platform key | org |
orgs_keys_retire | Retire a key | org |
orgs_keys_revoke | Revoke a key | org |
orgs_agents_create | Connect an agent | org |
orgs_agents_rotate | Rotate an agent's secret | org |
orgs_agents_revoke | Revoke an agent | org |
orgs_apps_create | Register an app | org |
orgs_apps_update | Change an app | org |
orgs_apps_rotate | Give an app a new client id | org |
orgs_apps_revoke | Revoke an app | org |
orgs_apps_review_request | Ask for sensitive scopes | org |
orgs_domains_add | Add a domain | org |
orgs_domains_verify | Verify a domain | org |
orgs_domains_remove | Remove a domain | org |
orgs_apps_policy_get | See the apps your people use | org |
orgs_apps_policy_set | Allow or block apps | org |
admin_apps_reviews_list (staff) | List app reviews | org |
admin_staff_list (staff) | List instruction.md's staff | org |
admin_staff_set (staff) | Change instruction.md's staff | org |
admin_apps_review (staff) | Decide an app review | org |
instructions_activity_list | List recent activity | insights |
instructions_audit_query | Query the audit trail | insights |
instructions_audit_export | Export the audit | insights |
orgs_billing_checkout | Upgrade the plan | billing |
orgs_billing_portal | Open the billing portal | billing |
orgs_spending_set | Set the spending limit | billing |
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 indetails.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.