API REFERENCE

The MCP OAuth API

Per-user MCP OAuth. When a tool server needs the end user's own account, these endpoints list what can be connected, start the consent flow, and revoke it later.

Some MCP servers act on behalf of the individual user, not the project. For those you use per-user OAuth: the end user connects their own account from inside the widget, EERRAA runs an OAuth 2.1 authorization_code flow with PKCE, and the resulting token is stored per user and injected only into that user's tool calls. These endpoints drive that flow. The widget's ERA.connectMcp(serverId) helper calls them for you, but you can build your own UI.

Per-user MCP OAuth is a signed-identity feature. Both start and revoke need a signed user_context, or they return SIGNED_IDENTITY_REQUIRED. Shared connections (admin connects once for the whole project) are configured in Settings and do not use these routes.

List connectable servers

GET/v1/oauth/mcp/servers

Returns the project's MCP servers that are configured for per-user OAuth, with whether the current user has already connected each one. Use it to render connect and disconnect buttons.

bash

curl https://eerraa.online/v1/oauth/mcp/servers \
  -H "Authorization: Bearer era_your_project_key" \
  -H "X-Era-User: %7B...signed...%7D"

json

{
  "servers": [
    { "server_id": "github", "name": "GitHub", "connected": false },
    { "server_id": "notion", "name": "Notion", "connected": true }
  ]
}

Field	Type	Description
`server_id`	string	Stable id you pass to start and revoke.
`name`	string	Human label for the server.
`connected`	boolean	Whether this user already has a valid connection.

Start a connection

POST/v1/oauth/mcp/start

Begins the OAuth flow for one server and one user. EERRAA generates the PKCE challenge and state, then returns an authorize_url. Send the user there (a popup or a redirect). When they approve, the provider calls EERRAA's callback, the token is exchanged and stored, and that user's future chats can call the server's tools.

Field	Type	Description
`user_context`required	object	The signed identity of the connecting user. Ties the token to this user.
`server_id`required	string	Which server to connect, from the servers list.

bash

curl -X POST https://eerraa.online/v1/oauth/mcp/start \
  -H "Authorization: Bearer era_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{
    "server_id": "github",
    "user_context": { "id": "u_42", "_ts": 1735689600, "_sig": "a1b2c3..." }
  }'

json

{ "authorize_url": "https://github.com/login/oauth/authorize?client_id=...&code_challenge=...&state=..." }

You do not handle the callback yourself. EERRAA owns the redirect URI, verifies state, and completes the PKCE exchange. After the popup closes, re-fetch the servers list to see connected: true.

Revoke a connection

DELETE/v1/oauth/mcp/connection/{server_id}

Disconnects the current user from one server and deletes their stored token. Their chats can no longer call that server's tools until they connect again.

bash

curl -X DELETE https://eerraa.online/v1/oauth/mcp/connection/github \
  -H "Authorization: Bearer era_your_project_key" \
  -H "X-Era-User: %7B...signed...%7D"

json

{ "deleted": true, "server_id": "github" }

PREVIOUSScheduled Tasks API NEXTWidget API