MCP server

Authentication

How MCP clients authenticate to Arachne: personal access tokens (the recommended path), OAuth access tokens from Arachne's Cognito pool, and the limits and error codes that protect the endpoint.

Every request to https://arachne.withaadhi.com/mcp carries Authorization: Bearer <token>. Two kinds of token are accepted:

Personal access tokens#

Create one#

1. Dashboard → MCP access tokensSign in to the app; the section is at the bottom of the Dashboard.
2. Label it and click Create tokenUse a label that names the client and machine, so you know what to revoke later.
3. Copy it onceThe full token is displayed once. Arachne stores only its SHA-256 hash, so it can never be shown again; if you lose it, revoke it and create another.

Use it#

POST /mcp HTTP/1.1
Host: arachne.withaadhi.com
Authorization: Bearer arpat_REPLACE_WITH_YOUR_TOKEN
Content-Type: application/json

Keep it in an environment variable or your client's secret storage and reference it from config:

export ARACHNE_TOKEN="arpat_REPLACE_WITH_YOUR_TOKEN"   # e.g. in ~/.zshrc, or load it from your password manager's CLI

[Environment]::SetEnvironmentVariable("ARACHNE_TOKEN", "arpat_REPLACE_WITH_YOUR_TOKEN", "User")

What a token can do#

• It acts as you, in the organisation it was created in (your personal one by default).
• Its permissions follow your live role. A token has no scopes of its own: on every request Arachne looks up your current role in that organisation and grants the matching tool scopes. Promote, demote or remove a person and their existing tokens change immediately; there is nothing to reissue.
• It can be revoked at any time from the same dashboard section. A revoked token gets 401 on its next request. The list shows when each token was last used.
• Up to 25 active tokens per person. Creating a 26th returns token_limit.
• Tokens do not expire. Rotate them yourself: create a new token, update your client, revoke the old one. Doing this every few months, and whenever a laptop or CI secret changes hands, is a good habit.
• Tokens are managed only from a signed-in browser session. A token cannot create, list or revoke tokens.

How a request is checked#

sequenceDiagram
  autonumber
  participant C as MCP client
  participant S as Arachne /mcp
  participant DB as Token + membership store
  C->>S: POST /mcp, Authorization: Bearer arpat_...
  S->>S: per-IP rate limit and lockout (before any token work)
  S->>S: body at most 256 KiB
  S->>S: prefix arpat_ means PAT, never parsed as a JWT
  S->>DB: look up SHA-256(token)
  alt unknown, malformed or revoked
    DB-->>S: none
    S-->>C: 401 invalid_token (counts as an IP auth failure)
  else live token
    DB-->>S: account + organisation
    S->>DB: live role of that person in that organisation
    alt no longer a member
      S-->>C: 403 insufficient_scope
    else member
      S->>S: tool scopes granted from the role, last-used bumped
      S->>S: per-person rate limit, then tool scope + role check
      S-->>C: 200 JSON-RPC result
    end
  end

OAuth with Cognito#

Clients that implement OAuth can use an access token from Arachne's Cognito user pool instead of a PAT. This path exists for clients that support pre-registered OAuth clients; it is not the recommended way to connect today.

What the server does with such a token: it verifies the signature against the pool's keys, the issuer and the expiry; a Cognito access token has no audience, so it must carry the …/mcp/invoke scope. Arachne then fetches your email from the pool's UserInfo endpoint with the same token (nothing is stored), signs you in exactly like a web login (same identity, first use creates the account), and acts in your personal organisation with your role's tool scopes.

For Claude Code, which supports pre-registered clients, the configuration would look like this (replace the client id):

claude mcp add-json arachne '{"type":"http","url":"https://arachne.withaadhi.com/mcp",
  "oauth":{"clientId":"YOUR_MCP_CLIENT_ID","callbackPort":8976,
           "scopes":"openid email https://arachne.withaadhi.com/mcp/invoke"}}'
# then, inside Claude Code: /mcp  -> arachne -> authenticate in the browser

Limits and error codes#