Register for part 2 of our Device Identity Webinar Series!

MCP Gateway Reference

This page lists the values, limits, and messages you meet when you run the Smallstep MCP gateway.

The MCP gateway is in early access. Contact Smallstep to turn it on for your team.

Policy schema

Access policies are written in Cedar and validated against schema version 2026-09-01. The schema is the same for every team. Every name is in the Smallstep namespace.

Entities

The principal of every request is the user. The device and the MCP client are in the request's context.

EntityIdentified byAttributes
Smallstep::UserThe user's email addressemail
Smallstep::DeviceThe device's ID in your inventoryos, os_version, ownership, assurance, lifecycle, enrollment, tags, shared, and optionally serial, hostname, agent_version
Smallstep::ClientThe MCP client's namename, and optionally version
Smallstep::UpstreamThe MCP server's URLidentifier, host
Smallstep::ToolThe MCP server's URL, then #, then the tool namename, upstream_host
Smallstep::TeamYour team's IDNone

In a policy, an MCP server is a Smallstep::Upstream. A tool belongs to its MCP server, so resource in Smallstep::Upstream::"<url>" matches every tool of that server.

Device attributes hold the values from your device inventory, in upper case. ownership is COMPANY_OWNED, USER_OWNED, or UNKNOWN. assurance is HIGH, NORMAL, or NO_ASSURANCE. tags is a set of strings, and shared is a boolean.

The MCP client reports its own name and version when it opens a session. The gateway can't verify them. A rule on context.client separates well-behaved clients, and it isn't a security boundary.

Request context

AttributeValuePresent
context.deviceThe device that presented the certificateAlways
context.clientThe MCP clientWhen the client reported a name
context.upstreamThe MCP serverAlways
context.methodThe JSON-RPC method of the callAlways
context.toolA record with the tool's nameFor tools/call
context.session_idThe gateway's session IDAlways
context.request_idThe gateway's ID for this callAlways
context.amrHow the device authenticated. The set contains "mtls"Always
context.source_ipThe address the connection came fromWhen known
context.timeWhen the gateway evaluated the callAlways
context.protocol_versionThe MCP protocol version the client asked forWhen the client sent one

A tool call's arguments aren't available to policy.

Actions

The gateway evaluates one action for each JSON-RPC call. The action is named after the call's method.

JSON-RPC methodActionResource
initializeSmallstep::Action::"initialize"The MCP server
tools/listSmallstep::Action::"tools/list"The MCP server
resources/listSmallstep::Action::"resources/list"The MCP server
resources/templates/listSmallstep::Action::"resources/templates/list"The MCP server
prompts/listSmallstep::Action::"prompts/list"The MCP server
tools/callSmallstep::Action::"tools/call"The tool
resources/readSmallstep::Action::"resources/read"The MCP server
prompts/getSmallstep::Action::"prompts/get"The MCP server
completion/completeSmallstep::Action::"completion/complete"The MCP server
Any other methodSmallstep::Action::"other"The MCP server

The four list actions are also in the group Smallstep::Action::"Discovery". Write action in Smallstep::Action::"Discovery" to match all of them.

For "other", context.method still holds the method the client sent.

Notifications aren't evaluated.

Rules to know

  • A session starts with initialize, and the policy applies to it. A policy set that permits only tools/call denies initialize, so in Enforce no session can open. Start from a policy that permits every action, then add forbid statements.
  • Cedar denies by default. A call goes ahead only when a permit statement matches and no forbid statement matches.
  • Write the MCP server's URL without a trailing slash. The gateway reduces a URL to lower-case scheme and host, no default port, no trailing slash, and no query string. https://api.githubcopilot.com/mcp/ is Smallstep::Upstream::"https://api.githubcopilot.com/mcp" in a policy. A statement that names the URL with a trailing slash never matches.
  • Check an optional attribute before you read it. Write context has client && context.client.name == "claude-code". Without the has check the statement doesn't pass validation.
  • resource.name exists only for tools/call. For every other action the resource is the MCP server, which has no name.
  • Match tools by name. The schema declares read_only, destructive, idempotent, and open_world on a tool. The gateway doesn't set them, so don't write rules on them.

Example policies

The baseline

The console offers three statements when you choose Start from the baseline. It saves all three and activates only baseline-allow.

Allow everything, as a base for forbid statements:

@id("baseline-allow")
@description("Allow everything; add forbid policies to restrict.")
permit (principal, action, resource);

Allow tool calls only from company-owned devices with high assurance:

@id("example-managed-devices-only")
@description("Only company-owned, high-assurance devices may call tools.")
forbid (principal, action == Smallstep::Action::"tools/call", resource)
unless { context.device.ownership == "COMPANY_OWNED" && context.device.assurance == "HIGH" };

Make one MCP server read-only for a group of users:

@id("example-github-read-only-for-contractors")
forbid (principal, action == Smallstep::Action::"tools/call",
        resource in Smallstep::Upstream::"https://api.githubcopilot.com/mcp")
when { principal.email like "*@contractor.example" && !(resource.name like "get_*" || resource.name like "list_*" || resource.name like "search_*") };

Block tools by name

This statement refuses calls to tools on one MCP server whose names start with save_, create_, update_, or delete_, for every user:

@id("linear-block-writes")
@description("Refuse Linear tools whose names start with save_, create_, update_, or delete_.")
forbid (
  principal,
  action == Smallstep::Action::"tools/call",
  resource in Smallstep::Upstream::"https://mcp.linear.app/mcp"
)
when {
  resource.name like "save_*" ||
  resource.name like "create_*" ||
  resource.name like "update_*" ||
  resource.name like "delete_*"
};

A statement that matches by name blocks only the names it matches. Read the MCP server's tool list before you rely on a statement like this one, and check it again when the server adds tools. To allow a fixed set of tools and refuse the rest, write the statement the way example-github-read-only-for-contractors does.

Policies, versions, and activations

ObjectWhat it is
PolicyOne Cedar statement. Its @id annotation is the policy's ID
VersionThe text of a policy at one save. Versions never change
ActivationA fixed list of policy versions. The gateway evaluates one activation at a time
ModeOff, Monitor, or Enforce, for the whole team

Saving a policy creates a new version and changes nothing else. The gateway evaluates a version only after you activate a set that includes it. Activating never changes the mode.

Changing the @id in the editor creates a different policy. A policy can be archived and never deleted. You can't archive a policy while the live activation includes it.

Modes

ModeCalls the policy allowsCalls the policy denies
OffForwarded. No decision is recordedForwarded. No decision is recorded
MonitorForwarded. The decision is recordedForwarded. The decision is recorded as "would refuse"
EnforceForwarded. The decision is recordedRefused. The decision is recorded as "deny"

Off is the starting mode. A team with no activation behaves as Off, and you can't choose Enforce until you activate a policy set.

In Enforce, the gateway also refuses a request it can't read as a single JSON-RPC message. That includes a JSON-RPC batch and a request body larger than 1 MiB.

If a forbid statement fails while it's being evaluated, the gateway denies the call.

What a refused call looks like

The gateway answers a refused call with a JSON-RPC error, so the MCP client receives it as part of the conversation:

{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32003,
    "message": "denied by policy linear-block-writes for https://mcp.linear.app/mcp tool save_issue",
    "data": {
      "session_id": "3f2b9c1e-7a54-4d0b-9e61-5c8a2d417f90",
      "request_id": "b81d4e06-2c9a-4f37-a5d2-6e0f93c17a48",
      "policies": ["linear-block-writes"]
    }
  }
}

The message names the forbid policies that matched. When no permit statement matched, the message names no policy: denied by policy for https://mcp.linear.app/mcp.

Limits

ItemLimit
Statements in one policy1
Policy ID1 to 128 characters from A-Z, a-z, 0-9, _, ., :, -
Policy text65,536 characters
Policy description1,024 characters
Policies in one activation256
Request body the gateway evaluates1 MiB
Captured tool arguments4,096 bytes for each call. Larger arguments aren't stored

Messages when a policy doesn't save

MessageCause
policy is missing the required @id("...") annotationThe statement has no @id
policy document must contain exactly one policy, found 2The text holds more than one statement
validating policy against schema 2026-09-01: … unrecognized action …The action isn't in the table of actions
validating policy against schema 2026-09-01: … attribute name on entity type Smallstep::Upstream not foundThe statement reads resource.name for an action other than tools/call
validating policy against schema 2026-09-01: … unable to guarantee safety of access to optional attribute …The statement reads an optional attribute without a has check
ENFORCE requires an activationYou chose Enforce before activating a policy set
policy is part of the active activationYou tried to archive a policy the live activation includes

Sessions

A session is one conversation between an MCP client and an MCP server through the gateway. It belongs to the user and the device that opened it.

Status

StatusMeaning
activeThe session is open
endedThe MCP client closed it
expiredNothing was sent for 24 hours, or the MCP server dropped its side
revokedAn administrator ended it
deniedThe session couldn't open. The policy refused it, or the user hasn't approved access to the MCP server yet
failedThe MCP server, or the gateway's token exchange, returned an error while the session was opening

End reason

End reasonMeaning
closed by clientThe MCP client ended the session
idle timeoutNo request for 24 hours
upstream goneThe MCP server reported that its session no longer exists
revokedAn administrator revoked the session. The console shows who
policy denyThe access policy refused the session in Enforce
consent requiredThe user has to approve access to the MCP server first
upstream errorThe MCP server refused or failed the opening request
exchange_errorThe gateway couldn't get an access token for the MCP server
policy_unavailableThe gateway couldn't read the team's policy
timeoutThe session didn't finish opening within 5 minutes

Timeline entries

EntryWhat it records
sessionA change in the session's status
A method name, such as tools/call · save_issueOne call, with the MCP server's HTTP status and the time it took
decisionOne policy evaluation: the outcome, the policies that determined it, the mode, and whether it was enforced
token exchangeThe gateway asked for an access token: "token issued" or "exchange failed"
consentThe user has to approve access first

A decision entry comes before the call it decided. An allowed call reads "not enforced" in every mode. A call the gateway refused reads "enforced", and its call entry reads "no upstream response".

The gateway keeps a user's access token for up to 60 seconds. A session that opens within that time has no token exchange entry.

A call's arguments appear in the timeline only when Capture tool arguments is on. Otherwise the entry shows a hash and the size of the arguments.

Revoking a session

Revoking ends one session. The next request in that session is refused, and the MCP client has to open a new one. The agent's MCP proxy on the device stops with the message session not found. Revoking doesn't block the user or the device. To keep someone out, use a forbid statement in Enforce, or remove the device from your inventory.

Decisions

OutcomeMeaning
allowThe policy allowed the call
would refuseThe policy denied the call, the mode was Monitor, and the call went ahead
denyThe policy denied the call, the mode was Enforce, and the call was refused

A decision marked "partial" means at least one statement failed while it was being evaluated.

A decision names the policies that determined it. Those are the forbid statements that matched, or the permit statements that matched when no forbid did. A decision with "no matching policy" means no permit statement matched.

Each decision records the activation it was evaluated against, so you can read back the exact policy text that was in force. A decision record holds IDs and hashes. It doesn't hold policy text or user attributes.

Audit events

MCP activity appears under Audit → Events in the category MCP.

TypeMessageWhen it's recorded
Session resolveddevice session resolvedThe gateway matched a device certificate to a device and a user. One connection can record this more than once
Session startedsession startedThe MCP server accepted a new session
Session endedsession, then the final status, such as "session denied"A session ended
Consent requiredconsent requiredA user has to approve access to an MCP server
Token issuedprovider token issuedThe token broker returned an access token
Tool calledtool call, then the tool nameA tool call passed the policy
Policy decisionpolicy allow or policy deny, then the method and toolThe gateway evaluated a call in Monitor or Enforce

How quickly changes apply

ChangeTakes effect within
Revoking a session10 seconds
Changing the mode, activating a policy set, or rolling back30 seconds
A device leaving your inventory, or its attributes changing60 seconds
Saving or removing trust rootsThe next connection
ItemLifetime
Device certificate for an MCP server24 hours, renewed by the agent
Link to approve access to an MCP server10 minutes
Idle sessionExpires after 24 hours
Sessions, timelines, and decisionsKept for 30 days after the session ends

Roles

TaskOwnerAdminDevice admin
Set or remove trust rootsYesYesNo
Add or delete an MCP serverYesYesNo
Read sessions, timelines, and decisions under AuditYesYesYes
Revoke a sessionYesYesNo
Save or archive a policy, activate a set, change the modeYesYesNo

Commands on the device

CommandWhat it does
step-agent mcp proxy --upstream <key>Runs the agent's MCP proxy for one MCP server. An MCP client starts this command as a local MCP server
step-agent mcp tools list --upstream <key>Opens a session through the gateway and lists the MCP server's tools. Use it to check the whole path from a device

<key> is the Upstream value of the MCP server in the console, such as linear. It has to match exactly, including case.

Messages from the agent

MessageCauseWhat to do
consent required: open <link> to authorize this upstreamThe user hasn't approved access to this MCP serverOpen the link, approve, and try again. Each user does this once for each MCP server
denied by policy for <url>The access policy refused the session or the call, and no permit statement matchedCheck that the live activation permits initialize, and read the decision under Audit → Decisions
denied by policy <id> for <url> tool <name>A forbid statement refused the callRead the decision under Audit → Decisions
failed to connect (session ID: <id>): session not foundThe session was revoked, or it expiredStart the MCP server again in the MCP client. The client opens a new session
no MCP proxy configured for upstream "<key>"The device has no MCP server with that Upstream valueCheck the value in the console, and wait for the agent to pick up new configuration
endpoint "<id>" has no usable certificateThe agent doesn't have a certificate for this MCP server yetCheck the device's assurance level and that it has a user assigned

When a user opens the approval link for an MCP server that has no OAuth client, the page says this upstream is not configured for your tenant. Delete the MCP server in the console and add it again with the client ID and client secret of your OAuth app.

Catalog entries

The catalog fills in the form when you add an MCP server. Use the URL in the last column when you name the server in a policy.

Catalog entryUpstreamURL in a policy
GitHubgithubhttps://api.githubcopilot.com/mcp
Linearlinearhttps://mcp.linear.app/mcp
Notionnotionhttps://mcp.notion.com/mcp
Slackslackhttps://mcp.slack.com/mcp
Sentrysentryhttps://mcp.sentry.dev/mcp
Figmafigmahttps://mcp.figma.com/mcp
Atlassian Jirajirahttps://mcp.atlassian.com/v1/mcp/authv2
Stripestripehttps://mcp.stripe.com

Choose Custom to add any other MCP server that uses OAuth.

Last updated on November 18, 2026

Smallstep MCP Gateway Reference for Policies, Sessions, and Errors | Smallstep