MCP (AI Assistants)

Arcan includes a built-in Model Context Protocol (MCP) server that lets AI assistants like Claude Desktop, Cursor, and Windsurf manage your secrets.

MCP is a JSON-RPC 2.0 protocol over stdio. The AI can list, organize, and delete secrets — but secret values are never exposed to the AI.

Starting the MCP Server

arcan mcp

This starts the MCP server on stdio. You don't run this directly — your AI assistant launches it automatically via its configuration.

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "arcan": {
      "command": "arcan",
      "args": ["mcp"],
      "env": {
        "ARCAN_TOKEN": "arc_your_token_here"
      }
    }
  }
}

Cursor / Windsurf

These editors use the same configuration format. Refer to their MCP documentation for the config file location.

Available Tools

Tool	Description	Security
arcan_health	Check server health	Safe
arcan_kv_list	List secret keys and metadata	Values never returned
arcan_kv_set	Set a secret	Returns SECURE_INPUT_REQUIRED
arcan_kv_delete	Delete a secret	Safe
arcan_realm_list	List realms	Safe
arcan_realm_create	Create a realm	Safe
arcan_audit_query	Query audit events	Safe
arcan_doctor	Run diagnostics	Safe
arcan_plugin_list	List installed plugins	Safe
arcan_auth_providers	List SSO providers	Safe

Security Model

• arcan_kv_list returns key names, metadata, and timestamps — never values
• arcan_kv_set refuses to accept values through AI — returns a SECURE_INPUT_REQUIRED error directing the user to run arcan kv set KEY VALUE in their terminal
• The AI can manage secrets (list, delete, organize) but can never read or write secret values
• All MCP operations are logged in the audit trail

Example Conversations

Managing secrets across environments

User: "What secrets do we have in the production realm?"

AI calls: arcan_kv_list(realm="production", env="prod")
AI shows:
  Found 5 secrets in production/prod:
  - DATABASE_URL      (v3, updated 2h ago)
  - REDIS_URL         (v2, updated 1d ago)
  - STRIPE_SECRET     (v1, updated 14d ago)
  - SENTRY_DSN        (v1, updated 30d ago)
  - API_KEY           (v5, updated 3h ago)

User: "Do we have the same secrets in staging?"

AI calls: arcan_kv_list(realm="production", env="staging")
AI shows:
  Found 4 secrets in production/staging:
  - DATABASE_URL      (v2, updated 5d ago)
  - REDIS_URL         (v1, updated 5d ago)
  - STRIPE_SECRET     (v1, updated 14d ago)
  - SENTRY_DSN        (v1, updated 30d ago)

  Note: API_KEY exists in prod but not in staging.

User: "Add the API_KEY to staging too."

AI calls: arcan_kv_set(realm="production", key="API_KEY", env="staging")
AI shows:
  For security, I can't accept secret values directly.
  Please run this in your terminal:
    arcan kv set API_KEY 'your-value' -r production -e staging

Auditing and diagnostics

User: "Who accessed secrets in the last hour?"

AI calls: arcan_audit_query(realm="production", action="secret.read", since="1h")
AI shows:
  Recent secret access (last 1h):
  - 14:23 [email protected]  read DATABASE_URL  (prod)
  - 14:18 ci-bot             read STRIPE_SECRET (prod)
  - 14:05 [email protected]  read REDIS_URL     (staging)
  - 13:58 k8s-eso-operator   read DATABASE_URL  (prod)

User: "Run diagnostics on the server."

AI calls: arcan_doctor()
AI shows:
  Arcan Health Check:
  - Server: v0.4.2, uptime 14d 3h
  - Store: PostgreSQL, 2.1ms latency
  - TLS: valid, expires in 287 days
  - Plugins: 3 loaded (postgres, redis, ssh)
  - Audit: 12,847 events, oldest 30d ago
  - Tokens: 8 active, 2 expired

User: "What plugins are installed?"

AI calls: arcan_plugin_list()
AI shows:
  Installed plugins:
  - postgres v0.1.0 (official) — Dynamic PostgreSQL credentials
  - redis    v0.1.0 (official) — Dynamic Redis credentials
  - ssh      v0.1.0 (official) — SSH certificate signing

Realm management

User: "Create a new realm for our analytics service."

AI calls: arcan_realm_create(name="Analytics Service", slug="analytics")
AI shows: Realm "analytics" created successfully.

User: "List all realms."

AI calls: arcan_realm_list()
AI shows:
  Realms:
  - default     (3 secrets)
  - production  (5 secrets across 3 envs)
  - analytics   (0 secrets, just created)

Configuration for Cursor

Add to your Cursor MCP config (.cursor/mcp.json in your project root or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "arcan": {
      "command": "arcan",
      "args": ["mcp"],
      "env": {
        "ARCAN_TOKEN": "arc_your_token_here"
      }
    }
  }
}

Restart Cursor after adding the configuration. The Arcan tools will appear in the tools list when you open the AI chat panel.

Security Model

The MCP server enforces a strict boundary between secret metadata and secret values:

┌─────────────────────────────────────────────────┐
│                AI Assistant (MCP Client)          │
│                                                   │
│  CAN see:                CAN NOT see:             │
│  - Secret key names      - Secret values          │
│  - Version numbers       - Encrypted data         │
│  - Timestamps            - Token strings          │
│  - Realm/env info        - Passwords              │
│  - Audit events          - Connection strings     │
│  - Plugin status                                   │
│  - Health diagnostics                              │
└────────────────────┬──────────────────────────────┘
                     │ JSON-RPC over stdio
┌────────────────────┴──────────────────────────────┐
│              Arcan MCP Server                      │
│                                                    │
│  arcan_kv_list  → returns keys + metadata only     │
│  arcan_kv_set   → returns SECURE_INPUT_REQUIRED    │
│  arcan_kv_delete → deletes, no value exposed       │
│  arcan_audit_query → action, actor, resource only  │
└────────────────────────────────────────────────────┘

Why values are never exposed:

• AI assistants log conversations and may store context in cloud services
• Secret values in AI context could be included in training data or logs
• The SECURE_INPUT_REQUIRED pattern ensures humans type secrets directly in a terminal, never through the AI

What the AI CAN do

Capability	Tool	Example
List all secret keys and metadata	arcan_kv_list	"What secrets are in the production realm?"
Delete a secret	arcan_kv_delete	"Remove the old API key from staging"
Create and list realms	arcan_realm_create, arcan_realm_list	"Create a realm for the analytics service"
Query the audit trail	arcan_audit_query	"Who accessed DATABASE_URL in the last hour?"
Run server diagnostics	arcan_doctor	"Is the Arcan server healthy?"
Check server health	arcan_health	"Is Arcan reachable?"
List installed plugins	arcan_plugin_list	"What dynamic credential engines are available?"
List SSO providers	arcan_auth_providers	"What login methods are configured?"

What the AI CANNOT do

Restriction	Reason
Read any secret value	arcan_kv_list returns key names and metadata only, never values
Write a secret value	arcan_kv_set returns SECURE_INPUT_REQUIRED -- the human must type the value in a terminal
Access encrypted storage	The MCP server has no path to raw encrypted data
Bypass token scopes	If the token is read-only, delete and create operations are denied
Export secrets to files	No export tool exists in the MCP server
Modify access policies	Policy management requires CLI or API access, not MCP

Configuration for Claude Code

Add to your project's .claude/settings.json:

{
  "mcpServers": {
    "arcan": {
      "command": "arcan",
      "args": ["mcp"],
      "env": {
        "ARCAN_TOKEN": "arc_your_token_here"
      }
    }
  }
}

Configuration for Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "arcan": {
      "command": "arcan",
      "args": ["mcp"],
      "env": {
        "ARCAN_TOKEN": "arc_your_token_here"
      }
    }
  }
}

Restart the editor after adding the configuration. The Arcan tools will appear in the AI assistant's tool list.