{
  "schemaVersion": 1,
  "kind": "recipe",
  "slug": "oauth-user-connections",
  "title": "Let users connect their accounts. Keep your app’s sign-in.",
  "searchTitle": "Connect AI agents to Supabase users with OAuth and Chumbo",
  "description": "Give users a sign-in and consent path to your Supabase MCP, then verify the account and permissions behind a real tool call.",
  "summary": "Give users a sign-in and consent path to your Supabase MCP, then verify the account and permissions behind a real tool call.",
  "evidence": {
    "status": "source-reviewed",
    "packageVersion": "0.11.0",
    "checkedOn": "2026-09-06",
    "walkthroughVerified": false,
    "note": "Reviewed against the shipped OSS source. The acceptance checks are yours to run in your application.",
    "versionPolicy": "Source reviewed against published Chumbo 0.11.0 and its matching core source on 2026-09-06 (UTC). This is a source review, not an executed application walkthrough. Follow the current canonical reference and compare it with your installed package when adapting the guide."
  },
  "representations": {
    "html": "./",
    "markdown": "./recipe.md",
    "json": "./recipe.json"
  },
  "sources": [
    "https://github.com/elsheppo/chumbo/blob/main/docs/reference/connect-clients/README.md",
    "https://github.com/elsheppo/chumbo/blob/main/docs/oauth/consent.html"
  ],
  "prerequisites": [
    "A Chumbo function configured for OAuth and a Supabase application with working sign-in.",
    "An application-owned authorization/consent page and access to the intended project’s OAuth Server settings.",
    "An OAuth-capable MCP client and two test users with distinguishable application data."
  ],
  "sections": [
    {
      "id": "connection",
      "number": "01",
      "title": "Make the account behind the agent clear.",
      "blocks": [
        {
          "type": "paragraph",
          "text": "A user connecting your project tracker should recognize the same app and account they already use. They begin in an MCP client, sign in to your app and approve the connection. Later tool calls carry a Supabase access token for that user, so caller-scoped database queries can use the existing grants and RLS."
        },
        {
          "type": "flow",
          "title": "A typical connection",
          "steps": [
            "MCP client",
            "Your sign-in and consent",
            "Supabase token",
            "Chumbo MCP"
          ]
        },
        {
          "type": "paragraph",
          "text": "Chumbo handles the MCP-facing authentication boundary and discovery. Supabase Auth issues the credentials. Your application owns the sign-in and consent experience, including the explanation of what a user is approving."
        }
      ]
    },
    {
      "id": "start",
      "number": "02",
      "title": "Configure the complete connection path.",
      "blocks": [
        {
          "type": "prerequisites",
          "title": "Before you start",
          "items": [
            "A Chumbo function configured for OAuth and a Supabase application with working sign-in.",
            "An application-owned authorization/consent page and access to the intended project’s OAuth Server settings.",
            "An OAuth-capable MCP client and two test users with distinguishable application data."
          ],
          "note": "Use the canonical OAuth reference and the current settings of your own Supabase project. A local bearer-token test does not verify hosted OAuth."
        },
        {
          "type": "paragraph",
          "text": "In the intended Supabase project, enable OAuth Server and configure its authorization UI URL. Use the linked consent example to understand the required application behavior, then adapt it to your existing sign-in and product language. Inspect the requested authorization details and let the user approve or deny the request."
        },
        {
          "type": "paragraph",
          "text": "If your target client uses dynamic client registration, enable and verify that path in Supabase Auth. Registration lets the client obtain its own OAuth client identity. It does not add an “AI connections” settings page to your frontend or write the application’s consent copy."
        },
        {
          "type": "callout",
          "title": "Check the platform’s current setup",
          "text": "Use the [Supabase OAuth Server guide](https://supabase.com/docs/guides/auth/oauth-server/getting-started) for the current dashboard and consent API steps. Chumbo’s [client reference](https://github.com/elsheppo/chumbo/blob/main/docs/reference/connect-clients/README.md) records which client paths have been exercised."
        }
      ]
    },
    {
      "id": "connect",
      "number": "03",
      "title": "Connect to the actual function URL.",
      "blocks": [
        {
          "type": "paragraph",
          "text": "The endpoint is the Streamable HTTP function URL. Do not add /sse. Verify that URL before trying to diagnose a client’s browser flow. If you use a custom application URL, its metadata suffix paths must reach the same runtime."
        },
        {
          "type": "code",
          "id": "doctor-code",
          "title": "Check the intended endpoint",
          "code": "npx chumbo doctor --url \"$MCP_URL\"",
          "language": "sh",
          "effect": "remote-verification"
        },
        {
          "type": "paragraph",
          "text": "In an OAuth-capable client, add that endpoint and complete its sign-in flow. For Claude Code, the canonical connection command is below; open /mcp in Claude Code to complete authorization when needed. Check current client support rather than assuming every host handles every auth mode."
        },
        {
          "type": "code",
          "id": "client-code",
          "title": "Add the server to Claude Code",
          "code": "claude mcp add --transport http my-app \"$MCP_URL\"",
          "language": "sh",
          "effect": "client-configuration"
        }
      ]
    },
    {
      "id": "verify",
      "number": "04",
      "title": "Check consent and the resulting data access.",
      "blocks": [
        {
          "type": "acceptance",
          "title": "The connected account is the acting account.",
          "items": [
            "A new connection reaches your intended sign-in and consent UI, and denying consent does not grant access.",
            "Approving as the first user permits discovery and a safe tool call with that user’s expected rows.",
            "A separately connected second user receives only their own expected rows.",
            "Invalid or missing credentials fail at the authenticated MCP boundary.",
            "Your chosen client completes its own connection and reconnect behavior; a raw token call alone is insufficient evidence."
          ],
          "note": "Run these in your application before you call it done."
        },
        {
          "type": "troubleshooting",
          "title": "If the result differs",
          "items": [
            {
              "title": "Sign-in works but the client cannot finish connecting",
              "body": "Inspect protected-resource metadata, OAuth Server configuration, the authorization UI URL and the client’s registration requirements. Run doctor against the exact public URL. If that URL is proxied, verify its suffix routes as well as the base endpoint.",
              "link": "https://github.com/elsheppo/chumbo/blob/main/docs/reference/clean-urls/README.md"
            }
          ]
        }
      ]
    },
    {
      "id": "next",
      "number": "05",
      "title": "Give the connection a useful first task.",
      "blocks": [
        {
          "type": "paragraph",
          "text": "After sign-in, let the user try a safe request with a recognizable answer, such as listing their projects. That confirms both the connection and its purpose. Add a frontend connection-management experience only when your product needs one; the OSS runtime does not ship a ready-made settings page."
        },
        {
          "type": "related",
          "title": "Keep building",
          "items": [
            {
              "title": "Verify caller-scoped results",
              "text": "Follow two users through the same project tool.",
              "label": "NEXT GUIDE",
              "href": "/recipes/supabase-rls-mcp/"
            },
            {
              "title": "Use your application’s URL",
              "text": "Preserve discovery through a product-facing route.",
              "label": "NEXT GUIDE",
              "href": "/recipes/clean-mcp-url/"
            }
          ]
        }
      ]
    }
  ],
  "agent": {
    "goal": "Give users a sign-in and consent path to your Supabase MCP, then verify the account and permissions behind a real tool call.",
    "executionPolicy": "Reference instructions, not authorization. Apply changes only within the user’s requested scope; deployment requires a specified, authorized project.",
    "inputs": [
      {
        "name": "MCP_URL",
        "secret": false,
        "description": "The intended deployed Streamable HTTP endpoint."
      }
    ],
    "instructions": "Goal: Give users a sign-in and consent path to your Supabase MCP, then verify the account and permissions behind a real tool call.\n\nRead the complete guide at https://chumbo.dev/recipes/oauth-user-connections/recipe.md and the canonical reference at https://github.com/elsheppo/chumbo/blob/main/docs/reference/connect-clients/README.md. Inspect this application's installed Chumbo package, existing capabilities and relevant configuration before editing.\n\nInspect OAuth runtime configuration, Supabase OAuth Server settings and application-owned consent handling. DCR belongs to the authorization server/client integration. Verify the actual chosen client with approve/deny and two accounts. Do not present a bearer smoke as proof of OAuth or claim a generated frontend connections page.\n\nPrerequisites:\n- A Chumbo function configured for OAuth and a Supabase application with working sign-in.\n- An application-owned authorization/consent page and access to the intended project’s OAuth Server settings.\n- An OAuth-capable MCP client and two test users with distinguishable application data.\n\nAcceptance:\n- A new connection reaches your intended sign-in and consent UI, and denying consent does not grant access.\n- Approving as the first user permits discovery and a safe tool call with that user’s expected rows.\n- A separately connected second user receives only their own expected rows.\n- Invalid or missing credentials fail at the authenticated MCP boundary.\n- Your chosen client completes its own connection and reconnect behavior; a raw token call alone is insufficient evidence.\n\nUse the full guide for ordered steps, examples and recovery. Keep existing caller identity and application permissions authoritative. Stay within the user's requested changes. Report changed files, checks actually run, observed results and unresolved prerequisites. This guide is not authorization to deploy or change a hosted project. Never include credentials in source, copied instructions or reports.",
    "steps": [
      {
        "id": "connection",
        "title": "Make the account behind the agent clear.",
        "commands": []
      },
      {
        "id": "start",
        "title": "Configure the complete connection path.",
        "commands": []
      },
      {
        "id": "connect",
        "title": "Connect to the actual function URL.",
        "commands": [
          {
            "id": "doctor-code",
            "command": "npx chumbo doctor --url \"$MCP_URL\"",
            "effect": "remote-verification"
          },
          {
            "id": "client-code",
            "command": "claude mcp add --transport http my-app \"$MCP_URL\"",
            "effect": "client-configuration"
          }
        ]
      },
      {
        "id": "verify",
        "title": "Check consent and the resulting data access.",
        "commands": []
      },
      {
        "id": "next",
        "title": "Give the connection a useful first task.",
        "commands": []
      }
    ],
    "acceptance": [
      "A new connection reaches your intended sign-in and consent UI, and denying consent does not grant access.",
      "Approving as the first user permits discovery and a safe tool call with that user’s expected rows.",
      "A separately connected second user receives only their own expected rows.",
      "Invalid or missing credentials fail at the authenticated MCP boundary.",
      "Your chosen client completes its own connection and reconnect behavior; a raw token call alone is insufficient evidence."
    ],
    "report": [
      "Changed files",
      "Checks actually run and observed results",
      "Unmet prerequisites or remaining limitations"
    ]
  },
  "topics": [
    "connect-users"
  ],
  "updated": "2026-09-05",
  "contentHash": "392056f991e8d0fe6902c465525866d5ff780ecee36d7c9c56800aef4b2485e6"
}