---
title: MCP & Tools
url: https://arcana.otnelhq.com/docs/mcp
---

# 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



| Command | Description |
| --- | --- |
| `arcana mcp add [name]` | Add an MCP server (interactive or via --url) |
| `arcana mcp list` / `ls` | List servers and connection status |
| `arcana mcp auth [name]` | Authenticate an OAuth-enabled MCP server |
| `arcana mcp logout [name]` | Remove OAuth credentials for a server |
| `arcana mcp debug <name>` | Debug OAuth connection and metadata discovery |




## Add Flags



| Flag | Description |
| --- | --- |
| `--url <url>` | URL for a remote MCP server (HTTP/HTTPS) |
| `--env KEY=VALUE` | Environment variable for a local MCP server (repeatable) |
| `--header KEY=VALUE` | HTTP header for a remote MCP server (repeatable) |




## 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.