MCP & Tools

Overview

MCP (Model Context Protocol) is a standard for connecting AI agents to external tools and data sources. Arcana supports both local and remote MCP servers, with OAuth authentication for remote connections.

Built-in tools include shell, filesystem, git, gateway, and skill tools — all running through explicit permission profiles with visible permissions.

Commands

List servers

arcana mcp list

Shows each configured server with its connection status:

✓ my-server connected (OAuth)
    https://example.com/mcp
✓ local-tools connected
    npx @modelcontextprotocol/server-filesystem /path
○ disabled-server disabled
    npx some-server

2 server(s)

Adding MCP servers

Interactive mode

arcana mcp add

The interactive wizard walks you through:

1. Scope — Current project or global (all projects)
2. Name — A unique identifier for the server
3. Type — Local (run a command) or Remote (connect to a URL)
4. Configuration — Command/URL, environment variables, headers, OAuth settings

Non-interactive mode

# Local MCP server
arcana mcp add my-tools -- npx @modelcontextprotocol/server-filesystem /path/to/dir

# Local with environment variables
arcana mcp add my-db --env DB_URL=postgres://localhost/mydb -- npx @anthropic-ai/server-postgres

# Remote MCP server
arcana mcp add my-api --url https://example.com/mcp

# Remote with custom headers
arcana mcp add my-api --url https://example.com/mcp --header "Authorization=Bearer token123"

Options

Configuration

MCP servers are configured in ~/.arcana/config.json (global) or arcana.json (project):

Local server

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "environment": {
        "NODE_ENV": "development"
      }
    }
  }
}

Remote server

{
  "mcp": {
    "my-api": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer token123"
      }
    }
  }
}

Remote with OAuth

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

If oauth is an empty object {}, Arcana will attempt dynamic client registration. If you have a pre-registered client, provide clientId and optionally clientSecret.

OAuth authentication

Remote MCP servers can require OAuth 2.0 authentication. Arcana handles the full OAuth flow including dynamic client registration, token refresh, and storage.

Authentication flow

1. Run arcana mcp auth and select the server
2. Arcana opens your browser to the OAuth authorization page
3. Sign in and authorize the application
4. Arcana stores the tokens and connects to the server

# Authenticate with a specific server
arcana mcp auth my-service

# List OAuth status for all servers
arcana mcp auth list

# Logout (remove stored credentials)
arcana mcp logout my-service

Auth status icons

Debugging connections

arcana mcp debug my-service

This tests the connection step by step:

• Checks stored auth status and token expiry
• Tests HTTP connectivity to the server URL
• Verifies OAuth metadata discovery
• Reports WWW-Authenticate headers and error details

Built-in tools

Arcana includes several built-in tools that run through the permission system:

Tool permissions

Each tool has a permission level that controls how Arcana handles tool calls:

Configure permissions in your config or let Arcana use sensible defaults.

Workspace trust

Project-local MCP servers and tools require workspace trust before they are loaded. This prevents untrusted project code from executing automatically.

Trust commands

# Trust the current workspace
arcana trust

# Check trust status
arcana trust status

# List all trusted workspaces
arcana trust list

# Revoke trust
arcana trust revoke

Dev / CI bypass

# Skip trust checks (dev only)
export ARCANA_DISABLE_WORKSPACE_TRUST=1

# Force-trust for CI
export ARCANA_TRUST_WORKSPACE=1

Common setups

Filesystem server

arcana mcp add filesystem -- npx @modelcontextprotocol/server-filesystem ~/projects

GitHub server

arcana mcp add github -- npx @modelcontextprotocol/server-github

PostgreSQL server

arcana mcp add postgres \\
  --env DATABASE_URL=postgres://localhost:5432/mydb \\
  -- npx @anthropic-ai/server-postgres

Remote API with OAuth

# Add remote server
arcana mcp add my-api --url https://api.example.com/mcp

# Authenticate
arcana mcp auth my-api

How it works

• MCP servers are started lazily on first use and persist for the session.
• Local servers run as child processes; remote servers connect via HTTP.
• OAuth tokens are stored securely and refreshed automatically.
• Tool calls go through the permission system — check, ask, or allow.
• Project-local MCP requires workspace trust; global MCP is always available.
• The agent selects relevant tools based on your prompt and context.