Auth & connecting
OAuth 2.1 with PKCE, dynamic client registration, RFC 9728/8414 discovery, token lifetimes, and legacy personal tokens.
Auth & connecting
The MCP endpoint requires a Bearer access token. Batohi acts as both the
resource server (/api/mcp) and the authorization server, using OAuth 2.1.
Flow
- Authorization code + PKCE (S256 only) — plain challenge is forbidden per OAuth 2.1.
- Consent is backed by your existing Batohi (Google) session.
- Dynamic Client Registration (RFC 7591) at
POST /api/oauth/register. Valid redirect URIs:https:, loopbackhttp:(127.0.0.1,localhost,[::1]), or custom app schemes (e.g.claude://,cursor://). - Single-use, SHA-256-hashed authorization codes (10-minute TTL).
Endpoints
| Endpoint | URL |
|---|---|
| MCP resource | POST https://batohi.com/api/mcp |
| Authorization | https://batohi.com/oauth/authorize |
| Token | POST https://batohi.com/api/oauth/token |
| Registration | POST https://batohi.com/api/oauth/register |
Discovery
| Well-known | Spec |
|---|---|
/.well-known/oauth-protected-resource | RFC 9728 |
/.well-known/oauth-authorization-server | RFC 8414 |
Both are also served path-suffixed /api/mcp (RFC 9728 §3.1) — the form a client
probes from the resource URL. A 401 from /api/mcp returns
WWW-Authenticate: Bearer resource_metadata="<origin>/.well-known/oauth-protected-resource",
which is how a client discovers the flow and offers one-click connect.
Tokens
| Token | Prefix | Lifetime |
|---|---|---|
| Access | mcpat_ | 1 hour |
| Refresh | mcprt_ | 30 days, rotated on use |
| Auth code | mcpac_ | 10 minutes |
| Client id | mcpcl_ | — |
All token-shaped values are stored only as SHA-256 hex. The single supported
scope is mcp:read. Grant types: authorization_code, refresh_token. Token
endpoint auth method: none (public client).
Legacy personal tokens
Personal tokens (prefix mcp_) minted before OAuth still work. They are
SHA-256 hashed, capped at 10 per user, and managed in the dashboard. OAuth
access tokens (mcpat_) are preferred.
Rate limiting
The MCP endpoint is currently unrated. Per-user throttling may be added later.
Protocol
Streamable HTTP, stateless. The server advertises protocol version
2025-06-18 and also accepts 2024-11-05 and 2025-03-26, echoing the
client's requested version. Server info: { name: "trackery", version: "1.0.0" }.
Capabilities: { tools: { listChanged: false } } — no resources, prompts, or
logging.