Documentation Index
Fetch the complete documentation index at: https://docs.shingleai.com/llms.txt
Use this file to discover all available pages before exploring further.
The ShingleAI MCP server is a protected resource. Clients authenticate using OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591), following the MCP authorization specification.
Modern MCP clients — Claude Desktop, Claude Code, Cursor, Windsurf, and the MCP Inspector — run the entire flow automatically. As an end user you only need to:
- Point the client at
https://mcp.shingleai.com.
- Sign in to ShingleAI when the consent screen opens in your browser.
- Approve the consent screen, choosing which tool categories the client may use.
The rest of this page describes the flow in detail for client developers and for anyone debugging a connection.
How the flow works
Client → /mcp (or /sse) (no token)
Server → 401 + WWW-Authenticate
Client → /.well-known/oauth-protected-resource/mcp (route-scoped; host-level also available)
Client → /.well-known/oauth-authorization-server
Client → POST /oauth/register (Dynamic Client Registration)
Client → /oauth/authorize (browser, with PKCE code_challenge)
User → consent screen
Server → redirect with auth code
Client → POST /oauth/token (code + code_verifier)
Server → access_token (+ refresh_token if offline_access)
Client → /mcp or /sse (Authorization: Bearer <token>)
Discovery
The server publishes two host-derived metadata documents. A client discovers everything else from these.
| Endpoint | Purpose |
|---|
/.well-known/oauth-protected-resource | RFC 9728 protected-resource metadata. Lists the authorization server. |
/.well-known/oauth-authorization-server | RFC 8414 authorization-server metadata. Lists /oauth/register, /oauth/authorize, /oauth/token, supported scopes, and PKCE methods. |
curl -s https://mcp.shingleai.com/.well-known/oauth-protected-resource | jq
curl -s https://mcp.shingleai.com/.well-known/oauth-authorization-server | jq
401 response shape
A request to /mcp or /sse without a valid Bearer token returns HTTP 401 with a WWW-Authenticate header pointing back to a route-scoped protected-resource metadata URL on the same host:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.shingleai.com/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing or invalid access token"
Content-Type: application/json
{"error":"invalid_token","error_description":"Missing or invalid access token"}
resource_metadata URL is route-scoped (/mcp and /sse advertise their own metadata documents); a host-level document is also available at /.well-known/oauth-protected-resource for clients that prefer it.
Dynamic Client Registration
Clients register themselves at POST /oauth/register per RFC 7591. Registration is open (no admin approval required) but rate-limited to 10 requests per 60 seconds per IP, so clients should cache the returned client_id (and any client_secret) and reuse it across launches rather than re-registering every time. Prefer the OS credential store (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) over a plaintext file on disk, especially for client_secret values.
PKCE
The server requires PKCE on every authorization request and only accepts the S256 code-challenge method. Plain PKCE is rejected — clients that send code_challenge_method=plain will fail the authorize step.
Scopes
Two scopes are advertised:
| Scope | Required | Purpose |
|---|
mcp | Yes | Access to the MCP transport endpoints. |
offline_access | No | Issues a refresh token alongside the access token. Request only for persistent or background clients; omit for interactive one-shot use, since the 90-day refresh token is a longer-lived credential. |
tools/list is filtered against that selection on every request.
Token lifetime
| Token | TTL | Notes |
|---|
| Access token | 60 min | Bearer token presented on /mcp and /sse. |
| Refresh token | 90 days | Issued only when offline_access was granted; rotated on use. |
POST /oauth/token with grant_type=refresh_token. Refresh tokens rotate on every use per OAuth 2.1.
Rate limits on the transport
Once authenticated, /mcp and /sse are rate-limited to 100 requests per 60 seconds per (user, client). A throttled response is HTTP 429 with a JSON-RPC error body (code: -32004, message: "Rate limit exceeded") and a Retry-After header. The server does not emit X-RateLimit-* headers.
Reference
