MCP Server for AI Agents
Connect Claude, Cursor, VS Code, and other Model Context Protocol clients to Atom, mint a least-privilege token for them, and see which tools and prompts they get.
MCP Server for AI Agents
Atom serves the Model Context Protocol at
POST /mcp on the main HTTP listener. Any MCP client that supports the
Streamable HTTP transport (Claude Code, Claude Desktop, Cursor, VS Code, and
others) can use it to answer questions like "why can this device not publish
to that channel?", search identities and the audit trail, and make scoped
changes such as granting a role.
The endpoint is always mounted; there is nothing to enable. Every tool runs a GraphQL operation as the token's owner, so an agent can do exactly what that token can do through GraphQL and nothing more.
1. Mint a token for the agent
MCP requests authenticate with Authorization: Bearer <token>. Cookies are
refused. Give the agent a scoped access token whose ceiling allows only the
actions it needs, not your session JWT or an unscoped API key: the agent's
effective access is the owner's live authority intersected with the ceiling
(see Scoped access tokens).
A read-only token for one tenant:
The token (atom_<id>_<secret>) is shown once. Store it in a secret manager or
an environment variable such as ATOM_TOKEN, not in a committed file.
Add actions to the ceiling only for the tools you want the agent to use:
| Tools | Action the owner and the ceiling must allow |
|---|---|
list_*, get_* | read on the objects |
authz_check, authz_bulk_check, authorized_object_ids | authz.check in the subject's tenant (or platform) |
authz_explain | policy.manage or manage at platform scope |
list_audit_logs | read or manage at platform scope, or read on audit_log in the tenant |
expiring_credentials, orphan_policies | manage at platform scope |
assign_role, remove_role_assignment | policy.manage in the tenant (or platform for global assignments) |
add_group_member, remove_group_member | manage on the group or its tenant |
With a tenant-scoped token, authorized_object_ids, list_role_assignments,
list_direct_policies, and list_audit_logs must be given tenantId; without
it they check platform scope and are refused. The tool descriptions tell the
model this.
2. Add Atom to your client
Replace https://atom.example.com with your Atom URL (http://localhost:8080
for the quick start stack).
Claude Code
Or share it with a project through .mcp.json; Claude Code expands
${ATOM_TOKEN} from each developer's environment:
Run /mcp inside Claude Code to confirm atom is connected.
Claude Desktop
Claude Desktop's custom connectors expect OAuth, which Atom's MCP endpoint does
not offer yet (see Limitations). Use the
mcp-remote bridge (requires
Node.js) in claude_desktop_config.json instead:
Restart Claude Desktop after editing the file.
Cursor
~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
VS Code
.vscode/mcp.json; VS Code prompts for the token once and stores it securely:
Other clients
Point any Streamable HTTP client at <atom-url>/mcp with the
Authorization: Bearer header. Clients that only speak stdio can use
mcp-remote as shown for Claude Desktop.
3. Check the connection
Call a tool directly:
A 401 means the token is missing, malformed, revoked, or expired. A tool result
with "isError": true carries the GraphQL error, most often a denial because
the token's ceiling or the owner's grants do not cover that tool.
Tools
| Tool | What it does | Kind |
|---|---|---|
authz_check | Is subject X allowed to do action Y on object Z? | read |
authz_explain | Same, plus every grant evaluated and the one that decided | read |
authz_bulk_check | Up to 20 checks in one call, results in input order | read |
authorized_object_ids | The reverse: which entities, resources, groups, roles, ... can X do Y on? | read |
list_entities / get_entity | Search identities, fetch one with attributes and groups | read |
list_resources / get_resource | Search resources, fetch one | read |
list_tenants | Search tenants | read |
list_groups / list_group_members | Walk the group hierarchy and membership | read |
list_entity_groups | Groups an entity is a direct member of | read |
list_roles | Roles with their permission blocks and actions | read |
list_role_assignments | Who holds which role (direct assignments only) | read |
list_direct_policies | Permission blocks granted to a subject without a role | read |
list_audit_logs | Search the audit trail by actor, target, event, outcome, time | read |
expiring_credentials | Credentials expiring soon or already expired (metadata only) | read |
orphan_policies | Assignments whose subject, role, or block no longer exists | read |
assign_role | Grant a role to an entity or group | write |
add_group_member | Add an entity to a group | write |
remove_role_assignment | Revoke a role assignment | write |
remove_group_member | Remove an entity from a group | write |
Read tools are marked readOnlyHint, so clients can run them without asking.
Every write tool is marked destructiveHint, including assign_role and
add_group_member: a role or group can carry a deny, and deny overrides allow,
so granting one can remove access. Clients that confirm destructive tools ask
before each of them. List tools page with limit / offset and return a
total count.
No tool returns a secret: there is no tool to mint a token, reveal a credential, or rotate keys, because tool output lands in the model's context and the client's logs. Credential revocation is not offered either: the revoke mutations refuse scoped access tokens by design, so it stays an administrator action in the admin UI or GraphQL API.
Prompts
Prompts are ready-made workflows that appear in the client's prompt or slash
command menu (in Claude Code, as /mcp__atom__<name>). They only produce
instructions for your model; every step still runs as a normal tool call under
the agent's token.
| Prompt | Arguments | What it does |
|---|---|---|
why_denied | subjectId, action, objectId, optional objectKind | Explains an allow or deny decision and suggests the smallest fix. Read-only. |
access_review | tenantId | Reviews roles, assignments, and direct policies in a tenant and flags broad or stale grants. Read-only. |
credential_hygiene | optional days (default 30) | Lists expiring and expired credentials, failing credential logins, and orphaned assignments. Read-only; needs platform manage. |
offboard_entity | entityId | Gathers an entity's roles, direct policies, and groups, presents a removal plan, and removes roles and group memberships only after you confirm. |
Security
- Authorization is the GraphQL authorization. Tools add no permissions and skip no checks: control-plane gates, PDP decisions, the token ceiling, and audit and domain events all behave as for the same GraphQL call.
- Arguments are validated before execution. Every call must match its
advertised input schema, including required fields, types, formats, and
bounds. Unknown arguments such as
dryRunare rejected; no mutation runs. - Use least privilege. Prefer a read-only ceiling. Grant write actions only to tokens for agents you expect to change access, and give those tokens an expiry.
- Browser protection. Cookie auth is refused, and a request with an
Originheader must matchATOM_CORS_ALLOWED_ORIGINS, which blocks DNS rebinding attacks from web pages. Trusted browser clients may send theMCP-Protocol-Versionheader through CORS. - Rate limits.
/mcpshares the GraphQL rate-limit bucket and request body limit. - Use TLS. The token is a bearer credential; expose
/mcponly over HTTPS outside localhost. - Revoke an agent's access at any time with
revokeAccessToken; the next request fails. - Tracing. Audit and domain events from a tool call are the same as from
the GraphQL call it runs. Each tool call also logs an
mcp tool callline with the tool name, the caller's entity id, and whether it failed, so you can tie events to MCP in your log pipeline.
Limitations
- No OAuth sign-in. Atom does not yet act as the OAuth authorization server the MCP authorization spec describes, so clients cannot discover a login flow. They must be configured with a token as shown above.
- Stateless transport. Each request is answered directly with JSON. There
are no sessions, server-sent events, progress notifications, or
server-initiated requests;
GET /mcpreturns 405. - Protocol version 2025-06-18 only. Older clients that need
2025-03-26(which requires JSON-RPC batching) are not supported; a request whoseMCP-Protocol-Versionheader names another version gets 400. - Audit rows do not record MCP. Audit events do not say which surface a
call came through; use the
mcp tool calllog line to correlate.