MCP & Tools

Arcana supports the Model Context Protocol (MCP), an open standard for connecting AI models to external tools and data sources. MCP servers let you extend Arcana with custom capabilities — database queries, API integrations, file operations, and more — all controlled through a unified interface.

How MCP Works

An MCP server exposes tools (functions the model can call), resources (data the model can read), and prompts (templates the model can use). Arcana connects to MCP servers at startup and makes their capabilities available to the AI during your session.

┌─────────────┐    MCP Protocol     ┌──────────────┐
│   Arcana    │ ──────────────────► │  MCP Server  │
│  (client)   │ ◄────────────────── │  (tools,     │
│             │                     │   resources) │
└─────────────┘                     └──────────────┘

Adding MCP Servers

You can connect Arcana to any MCP-compatible server using arcana mcp add.

# Connect to a remote MCP server via HTTP
arcana mcp add my-tools --url http://localhost:3001

# Connect to a cloud MCP server
arcana mcp add analytics --url https://mcp.example.com

# Add HTTP headers for authenticated servers
arcana mcp add secure-api --url https://api.example.com/mcp \
  --header "Authorization: Bearer sk-..."

# List connected servers
arcana mcp list

# Authenticate an OAuth-enabled MCP server
arcana mcp auth my-tools

# Remove OAuth credentials
arcana mcp logout my-tools

# Debug OAuth connection issues
arcana mcp debug my-tools

Configuration Format

MCP servers are configured in ~/.config/arcana/arcana.json under the mcp key. Servers can be remote (HTTP/SSE) or local (spawned subprocess):

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "."],
      "environment": {
        "HOME": "/home/user"
      }
    },
    "my-api": {
      "type": "remote",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer sk-..."
      }
    }
  }
}

OAuth Authentication

Remote MCP servers can use OAuth for authentication. Arcana supports dynamic client registration (DCR) and the full authorization code flow. When a server requires OAuth but hasn't been authenticated, Arcana will prompt you or you can authenticate explicitly:

# Start OAuth flow for a server
arcana mcp auth my-api

# Check auth status of all OAuth servers
arcana mcp auth list

# Remove stored credentials (forces re-auth next time)
arcana mcp logout my-api

# Debug connection and OAuth metadata discovery
arcana mcp debug my-api

For servers that require pre-registered client credentials, include them in the config:

"my-api": {
  "type": "remote",
  "url": "https://mcp.example.com",
  "oauth": {
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret"
  }
}

Command Reference

Add Flags

Built-in vs MCP Tools

Arcana ships with native tools available by default, independent of MCP:

• shell — Execute shell commands
• filesystem — Read and write files
• http — Make HTTP requests
• memory — Search and store facts in persistent memory

MCP servers add their own tools on top of these. Tools from an MCP server named "browser" appear as mcp_browser_navigate, mcp_browser_snapshot, etc. When you add an MCP server, its tools become available alongside Arcana's native tools in every session.