Connect any MCP client to UnderSelf

https://api.underself.io/mcp

Looking for the friendly version? See the guide for Claude, Grok, ChatGPT, Gemini or Meta Muse, or see every supported app.

What your client needs#

The OAuth flow, step by step#

• Call without a token. POST https://api.underself.io/mcp answers 401 with WWW-Authenticate: Bearer resource_metadata="https://api.underself.io/.well-known/oauth-protected-resource/mcp".
• Read the resource metadata. GET /.well-known/oauth-protected-resource/mcp names the resource (https://api.underself.io/mcp), the authorization server (https://api.underself.io) and the scopes.
• Read the authorization server metadata. GET /.well-known/oauth-authorization-server lists the authorize, token, registration and revocation endpoints, S256, and the supported grants.
• Register. POST your client metadata, including your redirect URIs, to the registration_endpoint. You get a client_id, and a client_secret if you asked for one.
• Authorize. Open the authorization_endpoint in the user's browser with response_type=code, your client_id, redirect_uri, state, code_challenge, code_challenge_method=S256 and resource=https://api.underself.io/mcp.
• Consent. UnderSelf sends the user to app.underself.io/connect/. They sign in with Google or Apple, see your app's name, the host you send them back to and what you can do, and choose Approve or Cancel. On Approve, the browser returns to your redirect_uri with code, state and iss.
• Get tokens. POST the code and your code_verifier to the token_endpoint. You get an access token (a JWT with audience https://api.underself.io/mcp, valid 15 minutes) and a refresh token.
• Call tools. POST /mcp with the bearer token: initialize, tools/list, tools/call. Refresh before the access token expires.

curl -s https://api.underself.io/.well-known/oauth-protected-resource/mcp
curl -s https://api.underself.io/.well-known/oauth-authorization-server

Tokens and lifetimes#

The tools in short#

tools/list shows only the tools the token's scopes allow. A connection reaches nothing outside these six: no delete, no billing, no account changes. Full inputs and outputs are in the tools reference.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_dreams",
    "arguments": { "limit": 2 }
  }
}

{
  "dreams": [
    {
      "dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
      "date": "2026-09-23",
      "summary": "Walking through a familiar house that keeps opening onto new rooms.",
      "has_reading": true
    },
    {
      "dream_id": "3f2a9c1e-0000-4000-8000-000000000002",
      "date": "2026-09-21",
      "summary": "A slow train along a coast at dusk.",
      "has_reading": false
    }
  ],
  "page": 1,
  "total": 14,
  "total_pages": 7
}

Every result carries the JSON both as structuredContent and as text, for clients that read only text. A failure is a normal tool result with isError: true and one plain sentence your assistant can read aloud.

What each error means#

Retries and slow readings#

• Retries are safe. record_dream with the same text from the same account within 10 minutes returns the earlier dream with duplicate: true, so an agent retry never spends a second dream.
• Readings take time. A reading can take up to about two minutes. If it runs long, record_dream still returns the saved dream_id with a note; call get_dream a minute later, and analyze_dream only if it still has no reading.
• Partial saves. If the dream was started but its text did not save, the result has status: "incomplete" and the dream_id. Call record_dream again with the same text within 10 minutes to finish it on the same dream.

Rate limits#

• About 60 requests a minute per account on /mcp.
• A higher ceiling per network address, set so that assistant platforms calling from shared addresses are not throttled together.
• Client registration is limited per network address per hour.
• Plan limits on new dreams and readings are the same as in the UnderSelf app.

Questions, or a client that will not connect? Write to info@underself.io.