Connect & authenticate

Connecting to the Busymate MCP server is a standard OAuth 2.1 flow — register, authorize in the browser, and you're in. Most MCP clients (Claude Desktop, Cursor) do the whole dance for you; you just paste the URL and sign in.

The endpoint

https://mcp.busymate.net

This single hostname serves both the JSON-RPC tool surface and the OAuth 2.1 authorization server. The server advertises its endpoints at the standard discovery URLs:

GET https://mcp.busymate.net/.well-known/oauth-authorization-server
GET https://mcp.busymate.net/.well-known/oauth-protected-resource

Those return the live authorization_endpoint, token_endpoint, and registration_endpoint (under /authorize, /token, /register).

The auth model in one paragraph

Auth is OAuth 2.1, one path. An external client registers itself with Dynamic Client Registration (DCR), then runs an authorization-code flow with PKCE (code_challenge_method=S256). You complete the consent in the browser by signing in with your normal Busymate (Supabase) login; the server hands back an access token whose jti is recorded in the api_tokens table with label='oauth'. That same token then authenticates every Busymate service — MCP, REST, Realtime, and Edge Functions. There is no pasted universal token and no separate API key to manage.

The OAuth 2.1 flow

1. Register — the client POSTs its metadata to /register and gets back a client_id.
2. Authorize — it opens /authorize in your browser with a PKCE code_challenge.
3. Consent — you sign in with your Busymate login and approve.
4. Code — the server redirects back with an authorization code.
5. Token — the client exchanges the code (+ PKCE code_verifier) at /token for an access token.

You don't run these by hand — a compliant MCP client does. The steps below are just configuration.

Claude Desktop

Add Busymate as a remote MCP server. In Claude Desktop, open Settings → Connectors → Add custom connector and enter:

• Name: Busymate
• URL: https://mcp.busymate.net

Claude will open a browser window for the OAuth consent. Sign in with your Busymate login and approve — that's it.

If you prefer config-file form (or are on a build that reads claude_desktop_config.json), add an HTTP MCP server entry:

{
  "mcpServers": {
    "busymate": {
      "type": "http",
      "url": "https://mcp.busymate.net"
    }
  }
}

Cursor

In Cursor, open Settings → MCP → Add new MCP server, or add it to your mcp.json:

{
  "mcpServers": {
    "busymate": {
      "url": "https://mcp.busymate.net"
    }
  }
}

Cursor handles the OAuth handshake in your browser on first use.

curl (raw JSON-RPC)

Once you hold an access token (any OAuth-issued token works — the in-app consoles use the same type), every tool call is a JSON-RPC 2.0 POST. List the tools:

curl -s https://mcp.busymate.net \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Call one — here, list paired devices:

curl -s https://mcp.busymate.net \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "list_devices", "arguments": {} }
  }'

Calling a tool without a valid bearer token returns 401 with a WWW-Authenticate: Bearer resource_metadata="…" header pointing at the discovery document — that's the cue for an MCP client to start the OAuth flow.

In-dashboard consoles (first-party path)

The dashboard's built-in tool consoles don't make you run OAuth at all. When you're already signed in, they exchange your live session for an identical OAuth-type token at:

POST https://mcp.busymate.net/first-party-token

So the in-app explorer and an external Claude client end up holding the same kind of token and hitting the same tools — full parity, one auth model.

Next

• Tool reference — the full list of 188 tools and their permission gating.
• Prompts & examples — what to actually say once connected.