@aredotna/mcp

MCP server for the Are.na API. Provides 30+ auto-generated tools from the OpenAPI spec plus custom composite tools.

Quick start

The hosted server is available at https://mcp.are.na/mcp.

Claude Desktop (connector)

The easiest way to connect. Go to Settings > Connectors > Add custom connector and enter:

• Name: Are.na
• Remote MCP server URL: https://mcp.are.na/mcp

Leave the OAuth Client ID and Secret fields blank — the server supports Dynamic Client Registration. Click Add, then authorize with your Are.na account when prompted.

Claude Desktop (config file)

You can also add the server directly in claude_desktop_config.json. If your version supports the url format:

{
  "mcpServers": {
    "arena": {
      "type": "http",
      "url": "https://mcp.are.na/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ARENA_TOKEN"
      }
    }
  }
}

Get a personal access token from are.na/settings/personal-access-tokens.

If your version only supports command (stdio), you can use mcp-proxy to bridge to the remote server. Install uv first (brew install uv), then:

{
  "mcpServers": {
    "arena": {
      "command": "/opt/homebrew/bin/uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "-H",
        "Authorization",
        "Bearer YOUR_ARENA_TOKEN",
        "https://mcp.are.na/mcp"
      ]
    }
  }
}

Note: Use the full path to uvx (e.g. /opt/homebrew/bin/uvx). Claude Desktop may not have uvx on its PATH.

Claude Desktop (local)

To run the server locally via stdio, clone the repo, run yarn install && yarn generate, then use absolute paths in your config:

{
  "mcpServers": {
    "arena": {
      "command": "/path/to/arena/mcp/node_modules/.bin/tsx",
      "args": ["/path/to/arena/mcp/src/transports/stdio.ts"],
      "env": {
        "ARENA_ACCESS_TOKEN": "YOUR_ARENA_TOKEN"
      }
    }
  }
}

Note: You must use absolute paths for both command and args. Claude Desktop does not reliably resolve relative paths or respect cwd. Using yarn dev or bare npx tsx will not work — yarn writes to stdout, and npx without a cwd cannot find the script.

Claude Code

claude mcp add --transport http arena https://mcp.are.na/mcp

Authenticate via /mcp when prompted.

Cursor

Add the server under Settings > MCP Servers with URL https://mcp.are.na/mcp and an Authorization: Bearer YOUR_ARENA_TOKEN header.

Development

git clone https://github.com/aredotna/mcp.git
cd mcp
yarn install
yarn generate   # fetch OpenAPI spec, generate types + tools

Running locally

stdio — single-user, for use with Claude Desktop or other MCP clients:

ARENA_ACCESS_TOKEN=your-token yarn dev

HTTP — runs a local Cloudflare Workers dev server:

cp .dev.vars.example .dev.vars
# Set your tokens in .dev.vars (see .dev.vars.example)
yarn dev:http

The HTTP server requires a KV namespace for OAuth state. For local development, Wrangler provides an in-memory KV automatically. For production, create a KV namespace and update the id in wrangler.toml (KV is included in Cloudflare's free tier):

npx wrangler kv namespace create OAUTH_KV

You also need to set the Are.na OAuth application credentials as secrets:

npx wrangler secret put ARENA_OAUTH_CLIENT_ID
npx wrangler secret put ARENA_OAUTH_CLIENT_SECRET

Register your OAuth application at are.na/developers/oauth/applications with redirect URI https://mcp.are.na/callback (or http://127.0.0.1:8787/callback for local dev).

Testing

yarn typecheck
yarn test

Formatting

yarn format

Prettier runs automatically on staged files via a pre-commit hook.

Deployment

Pushes to main are automatically deployed to Cloudflare Workers via GitHub Actions.

To deploy manually:

yarn deploy

Requires CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID (set as GitHub repo secrets for CI, or via wrangler login locally).

Adding custom tools

Create a file in src/tools/custom/, export a register function, and add it to src/tools/index.ts. See src/tools/custom/search-and-connect.ts for an example.

Regenerating tools

When the Are.na API spec changes:

yarn generate

This fetches the latest spec and regenerates TypeScript types and tool registrations.