MCP Connectors

Summary

With OAuth configured, any OAuth-capable MCP client — Claude, ChatGPT, and other custom-connector hosts — can connect to your API's /mcp endpoint interactively. The user pastes one URL, signs in, approves an access level, and the agent gets scoped access to the MCP tools.

Connecting

Give users the MCP endpoint URL:

https://<your-api-origin>/mcp

Adding it as a custom connector triggers the whole flow automatically:

  1. The client calls /mcp, gets 401 with a WWW-Authenticate header pointing at /.well-known/oauth-protected-resource.
  2. It reads the protected-resource metadata, discovers the authorization server, and reads /.well-known/openid-configuration.
  3. It self-registers at POST /connect/register — no admin setup, no stored registration.
  4. It opens /connect/authorize in the user's browser; Core redirects to your consent page.
  5. The user signs in, picks an access level, and approves.
  6. The client exchanges the authorization code (with PKCE) for tokens at /connect/token.
  7. Tool calls run as the signed-in user, capped to the consented access level and the user's RBAC permissions.

The user can revoke the connection at any time from your Connected apps screen, or from the client's own settings.

Requirements

  • AddCoreOAuth and AddCoreMcpServer/UseCoreMcp wired as in Setup.
  • The endpoint must be reachable over HTTPS from the client's network. For local development use a tunnel (e.g. ngrok) and set OAuth:PublicOrigin to the tunnel origin.

Troubleshooting

Symptom Cause Fix
Client reports the server doesn't support OAuth Protected-resource metadata missing Call app.UseCoreMcp() so /.well-known/oauth-protected-resource is mapped
Connect succeeds, but tool calls fail with an invalid/rejected token Issuer mismatch behind a proxy or tunnel: tokens are minted on the public host but validated against the internal address Set OAuth:PublicOrigin to the public origin
/mcp returns 500 OAuth is not registered in this environment, so the validation scheme doesn't exist Ensure the OAuth config section is present (see Setup)
Authorize or token requests are rejected outright Plain HTTP Serve HTTPS or front the API with a tunnel
Agent writes fail with "read-only" or "cannot delete" The connection's consented access level caps the operation Reconnect and approve a higher level — the ceiling is per connection
Sign-in page rejects the return URL The consent app's configured API origin differs from the host serving /connect/authorize Point the consent app at the same public origin the client uses

Notes

  • Access tokens are encrypted; they can only be validated by the issuing deployment (same OAuth:Secret).
  • Rotating OAuth:Secret disconnects all clients; they re-register and users reconnect.
  • The generic MCP tool surface itself is documented in Expose entities via MCP.