@vorim/mcp-server

MCP server for AI agent identity, permissions, and audit trails.

Gives Claude, Cursor, VS Code, Windsurf, Google Antigravity, Grok Build, Cosine, and any MCP-compatible client 19 tools to manage AI agent identities through Vorim — register agents, check permissions, emit audit events, verify trust scores, and delegate credentials.

API key: create one in the Vorim dashboard under Settings, API keys. No account yet? Request access at vorim.ai. Documentation — Full API reference and guides.

Quick Start

This is a stdio server. Your MCP client starts it as a local process and passes VORIM_API_KEY in its environment, so put the key in the client config as shown below. See Which API-key scopes each tool needs before you create the key.

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vorim": {
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

Claude Code

claude mcp add vorim -e VORIM_API_KEY=agid_sk_live_... -- npx -y @vorim/mcp-server

Pass the key with -e so Claude Code stores it with the server entry. Exporting VORIM_API_KEY in your shell after adding the server does not reach it.

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "vorim": {
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "vorim": {
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "vorim": {
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

Google Antigravity

Add to the workspace config at .agents/mcp_config.json, or the global config at ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "vorim": {
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

Or add it from the UI: Settings → Customizations → Installed MCP Servers → Add MCP. Every agent Antigravity runs — in the editor, terminal, or browser — then gets the Vorim tools.

Grok Build (xAI)

Grok Build, xAI's terminal coding agent, supports MCP servers natively. Register Vorim with the CLI:

grok mcp add vorim -- npx -y @vorim/mcp-server

Then set the API key in the shell you start Grok Build from, before you start it. The server inherits Grok's environment at launch, so a key exported later does not reach it.

export VORIM_API_KEY=agid_sk_live_...

MCP servers are stored in ~/.grok/config.toml; manage them with the grok mcp commands. Every agent Grok Build runs then gets the Vorim tools.

Berd & Goose (Block)

Berd is Block's desktop app for AI agents, running on the Goose engine — an MCP client. Add Vorim as a Standard IO extension and every agent you run in Berd (or Goose) gets identity, permission checks before actions, and a signed audit trail.

Berd / Goose Desktop: open the sidebar → Extensions → Add custom extension. Set Type to Standard IO, Command to npx -y @vorim/mcp-server, and add an environment variable VORIM_API_KEY = your key.

Goose CLI: run goose configure → Add Extension → Command-Line Extension, then enter npx -y @vorim/mcp-server.

Or add it directly to ~/.config/goose/config.yaml:

extensions:
  vorim:
    enabled: true
    type: stdio
    cmd: npx
    args:
      - "-y"
      - "@vorim/mcp-server"
    env_keys:
      - VORIM_API_KEY
    timeout: 300

Store the key with goose configure so it lands in Goose's secret store; env_keys tells Goose which secret to pass to the server at launch.

Cosine

Cosine ships autonomous coding agents (Lumen) that plan a change, write it, and open a pull request without a human in the loop. Its CLI is an MCP client, so adding Vorim gives every agent it runs identity, a permission check before it acts, and a signed audit trail — the record you hand an auditor after an agent acted unsupervised.

Add it from the CLI:

cos mcp add --transport stdio -e VORIM_API_KEY=agid_sk_live_... vorim -- npx -y @vorim/mcp-server

Or edit ~/.cosine/mcp.json directly (%USERPROFILE%\.cosine\mcp.json on Windows):

{
  "mcpServers": {
    "vorim": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@vorim/mcp-server"],
      "env": {
        "VORIM_API_KEY": "agid_sk_live_..."
      }
    }
  }
}

Press Ctrl+J in the Cosine TUI and pick MCP servers to confirm Vorim connected.

OpenAI Agents SDK

The OpenAI Agents SDK can run this server locally through MCPServerStdio with command="npx", args=["-y", "@vorim/mcp-server"] and env={"VORIM_API_KEY": "agid_sk_live_..."}.

ChatGPT connectors and the remote MCP tool in the OpenAI Responses API only connect to MCP servers over HTTP at a public URL. This package is stdio only, so it does not work with them as published.

Tools

The server exposes 19 tools across seven categories:

Health

| Tool | Description | |------|-------------| | vorim_ping | Check API health and connectivity |

Agent Identity

| Tool | Description | |------|-------------| | vorim_register_agent | Register a new agent with an Ed25519 keypair | | vorim_get_agent | Get agent details by ID | | vorim_list_agents | List all agents (with pagination and status filter) | | vorim_update_agent | Update agent metadata | | vorim_revoke_agent | Permanently revoke an agent |

Permissions

| Tool | Description | |------|-------------| | vorim_check_permission | Check if an agent has a permission (sub-5ms via Redis) | | vorim_grant_permission | Grant a scoped permission with optional expiry and rate limits | | vorim_list_permissions | List all active permissions for an agent | | vorim_revoke_permission | Revoke a permission from an agent |

Audit

| Tool | Description | |------|-------------| | vorim_emit_event | Log an audit event (sign client-side via @vorim/sdk for tamper-evidence) | | vorim_export_audit | Export a signed audit bundle (SHA-256 manifest) |

Trust

| Tool | Description | |------|-------------| | vorim_verify_trust | Verify an agent's identity and trust score (0-100) |

Credential Delegation

| Tool | Description | |------|-------------| | vorim_register_ephemeral | Register a short-lived agent with did:key identity | | vorim_delegate_credential | Delegate a scoped credential to an agent | | vorim_request_token | Request a short-lived access token | | vorim_list_delegations | List credential delegations |

Onboarding

| Tool | Description | |------|-------------| | vorim_onboard_start | Start onboarding a user with no API key yet (device-authorization flow) | | vorim_onboard_check | Check whether the user has approved the onboarding request |

Which API-key scopes each tool needs

Each tool calls one Vorim API route, and that route checks one scope on your key. A key without the scope gets an INSUFFICIENT_SCOPE error for that tool only.

| Tool | API route | Key scope | |------|-----------|-----------| | vorim_ping | GET /health | none | | vorim_verify_trust | GET /v1/trust/verify/:agentId (public) | none | | vorim_onboard_start, vorim_onboard_check | POST /v1/auth/device, POST /v1/auth/device/token | none | | vorim_register_agent | POST /v1/agents | agents:write | | vorim_get_agent, vorim_list_agents | GET /v1/agents/:agentId, GET /v1/agents | agents:read | | vorim_update_agent, vorim_revoke_agent | PATCH / DELETE /v1/agents/:agentId | agents:write | | vorim_register_ephemeral | POST /v1/agents/ephemeral | agents:write | | vorim_check_permission | POST /v1/agents/:agentId/permissions/verify | permissions:read | | vorim_list_permissions | GET /v1/agents/:agentId/permissions | permissions:read | | vorim_grant_permission, vorim_revoke_permission | POST / DELETE /v1/agents/:agentId/permissions | permissions:write | | vorim_emit_event | POST /v1/audit/events | audit:write | | vorim_export_audit | POST /v1/audit/export | audit:read, and a plan with signed bundles (Starter or above, not Free) | | vorim_delegate_credential, vorim_request_token | POST /v1/credentials/delegations, POST /v1/credentials/token | credentials:write | | vorim_list_delegations | GET /v1/credentials/delegations | credentials:read |

Scopes are independent. agents:write does not grant agents:read, so a key that should use every tool needs all eight: agents:read, agents:write, permissions:read, permissions:write, audit:read, audit:write, credentials:read, credentials:write.

Starting without a key

If VORIM_API_KEY is not set, the server still starts but registers only the four tools that need no key: vorim_ping, vorim_verify_trust, vorim_onboard_start and vorim_onboard_check. It prints a note to stderr saying so.

vorim_onboard_start returns a code for a human to approve at vorim.ai/activate. Approving needs an owner or admin signed in to an existing Vorim organisation. vorim_onboard_check then returns a new API key with the agents:read, agents:write, permissions:read and audit:write scopes. Put that key in VORIM_API_KEY in your client config and restart the server to load the other tools. For tools that need other scopes, create a key in the dashboard instead.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | VORIM_API_KEY | Your Vorim API key (agid_sk_...). Without it only the four keyless tools load | Required for 15 of the 19 tools | | VORIM_BASE_URL | API base URL | https://api.vorim.ai |

Example Prompts

Once the MCP server is connected, you can ask your AI assistant:

• "Register a new agent called invoice-processor with read and execute permissions"
• "Check if agent agid_acme_a1b2c3d4 has agent:execute permission"
• "Show me the trust score for agent agid_acme_a1b2c3d4"
• "List all active agents"
• "Emit an audit event for agent agid_acme_a1b2c3d4 performing search_documents"
• "Export audit logs from the last 7 days"
• "Grant agent:transact permission to agid_acme_a1b2c3d4 with a rate limit of 100 per hour"
• "Create an ephemeral agent with a 1-hour TTL for a one-off task"

Running Standalone

VORIM_API_KEY=agid_sk_live_... npx -y @vorim/mcp-server

Or install globally:

npm install -g @vorim/mcp-server
VORIM_API_KEY=agid_sk_live_... vorim-mcp-server

Related

• @vorim/sdk — TypeScript SDK
• vorim (PyPI) — Python SDK
• @vorim/cli — CLI tool
• vorim.ai/docs — Documentation

License

MIT