Atom
Operations

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:

curl -s http://localhost:8080/graphql \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation($input: CreateAccessTokenInput!) { createAccessToken(input: $input) { credentialId token expiresAt } }",
    "variables": { "input": {
      "name": "claude-agent",
      "description": "MCP agent, read only",
      "permissions": [
        { "actions": ["read", "authz.check"], "scopeMode": "tenant", "tenantId": "<tenant-id>" }
      ]
    } }
  }' | jq -r .data.createAccessToken.token

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:

ToolsAction the owner and the ceiling must allow
list_*, get_*read on the objects
authz_check, authz_bulk_check, authorized_object_idsauthz.check in the subject's tenant (or platform)
authz_explainpolicy.manage or manage at platform scope
list_audit_logsread or manage at platform scope, or read on audit_log in the tenant
expiring_credentials, orphan_policiesmanage at platform scope
assign_role, remove_role_assignmentpolicy.manage in the tenant (or platform for global assignments)
add_group_member, remove_group_membermanage 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

claude mcp add --transport http atom https://atom.example.com/mcp \
  --header "Authorization: Bearer $ATOM_TOKEN"

Or share it with a project through .mcp.json; Claude Code expands ${ATOM_TOKEN} from each developer's environment:

{
  "mcpServers": {
    "atom": {
      "type": "http",
      "url": "https://atom.example.com/mcp",
      "headers": { "Authorization": "Bearer ${ATOM_TOKEN}" }
    }
  }
}

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:

{
  "mcpServers": {
    "atom": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://atom.example.com/mcp",
        "--header", "Authorization:${ATOM_AUTH}"
      ],
      "env": { "ATOM_AUTH": "Bearer atom_<id>_<secret>" }
    }
  }
}

Restart Claude Desktop after editing the file.

Cursor

~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "atom": {
      "url": "https://atom.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:ATOM_TOKEN}" }
    }
  }
}

VS Code

.vscode/mcp.json; VS Code prompts for the token once and stores it securely:

{
  "inputs": [
    { "type": "promptString", "id": "atom-token", "description": "Atom access token", "password": true }
  ],
  "servers": {
    "atom": {
      "type": "http",
      "url": "https://atom.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:atom-token}" }
    }
  }
}

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

curl -s https://atom.example.com/mcp \
  -H "Authorization: Bearer $ATOM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

Call a tool directly:

curl -s https://atom.example.com/mcp \
  -H "Authorization: Bearer $ATOM_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"authz_check",
        "arguments":{"subjectId":"<entity-id>","action":"read","resourceId":"<resource-id>"}}}' \
  | jq .result

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

ToolWhat it doesKind
authz_checkIs subject X allowed to do action Y on object Z?read
authz_explainSame, plus every grant evaluated and the one that decidedread
authz_bulk_checkUp to 20 checks in one call, results in input orderread
authorized_object_idsThe reverse: which entities, resources, groups, roles, ... can X do Y on?read
list_entities / get_entitySearch identities, fetch one with attributes and groupsread
list_resources / get_resourceSearch resources, fetch oneread
list_tenantsSearch tenantsread
list_groups / list_group_membersWalk the group hierarchy and membershipread
list_entity_groupsGroups an entity is a direct member ofread
list_rolesRoles with their permission blocks and actionsread
list_role_assignmentsWho holds which role (direct assignments only)read
list_direct_policiesPermission blocks granted to a subject without a roleread
list_audit_logsSearch the audit trail by actor, target, event, outcome, timeread
expiring_credentialsCredentials expiring soon or already expired (metadata only)read
orphan_policiesAssignments whose subject, role, or block no longer existsread
assign_roleGrant a role to an entity or groupwrite
add_group_memberAdd an entity to a groupwrite
remove_role_assignmentRevoke a role assignmentwrite
remove_group_memberRemove an entity from a groupwrite

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.

PromptArgumentsWhat it does
why_deniedsubjectId, action, objectId, optional objectKindExplains an allow or deny decision and suggests the smallest fix. Read-only.
access_reviewtenantIdReviews roles, assignments, and direct policies in a tenant and flags broad or stale grants. Read-only.
credential_hygieneoptional days (default 30)Lists expiring and expired credentials, failing credential logins, and orphaned assignments. Read-only; needs platform manage.
offboard_entityentityIdGathers 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 dryRun are 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 Origin header must match ATOM_CORS_ALLOWED_ORIGINS, which blocks DNS rebinding attacks from web pages. Trusted browser clients may send the MCP-Protocol-Version header through CORS.
  • Rate limits. /mcp shares the GraphQL rate-limit bucket and request body limit.
  • Use TLS. The token is a bearer credential; expose /mcp only 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 call line 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 /mcp returns 405.
  • Protocol version 2025-06-18 only. Older clients that need 2025-03-26 (which requires JSON-RPC batching) are not supported; a request whose MCP-Protocol-Version header 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 call log line to correlate.

On this page