Authentication

You give your client one URL. The client calls it, gets refused, and the refusal tells it where to send you to sign in. You sign in with your Eddie account. The client keeps the token it gets back and sends it on every later call.

There is no key to create, no secret to store and no header to write by hand. If your client asks for a client id or a client secret, leave both empty: the client registers itself as part of the flow.

Type

oauth2

Resource

https://mcp.heyeddie.ai/api/mcp

Token placement

Authorization: Bearer <access token>

Metadata document

https://mcp.heyeddie.ai/.well-known/oauth-protected-resource

1. The client calls the endpoint with no credential. The server answers 401 and a WWW-Authenticate header that names a metadata document.
2. The client fetches that document. It says which authorization server issues tokens for this endpoint.
3. The client registers itself with that authorization server, then sends you to sign in. The exchange uses the authorization code grant with proof key for code exchange.
4. The client sends Authorization: Bearer <token> on every call from then on, and refreshes the token when it expires.

Step one, as your client sees it:

HTTP/2 401
www-authenticate: Bearer error="invalid_token",
  error_description="No authorization provided",
  resource_metadata="https://mcp.heyeddie.ai/.well-known/oauth-protected-resource"

Step two, which you can run yourself — it needs no credential:

curl https://mcp.heyeddie.ai/.well-known/oauth-protected-resource

The document names this endpoint as the protected resource and lists the authorization server that issues tokens for it. Read it at run time rather than copying the values into your own configuration. The whole point of the document is that the server can move the sign-in without breaking clients.

Your Eddie account — the same one you use in the Eddie web application. Sign-in is handled by WorkOS AuthKit, which is also what signs you in to the application itself. There is no separate developer account and no separate password.

Tokens are issued for this endpoint alone. A token minted for another audience is rejected, so a credential cannot be borrowed from one Eddie surface and replayed against another.

Grant

Authorization code with proof key for code exchange (S256).

Client registration

Dynamic. Your client registers itself, unattended.

Refresh

The authorization server advertises the refresh_token grant and the offline_access scope. Whether your client asks for them, and how it renews a token, is the client’s business, not the server’s.

Sign-in scopes

The standard identity set: openid, profile, email, offline_access. They describe the sign-in, not what a tool may do.

Signing in is not the same as being allowed to change a project. What a tool call may do is decided per project, by the access you have to the project it names. The server publishes the two levels itself:

View

Read a project: its sources, transcripts, edits, comments, labels and frames. Every read-only tool needs it. A viewer can never reach a tool that writes.

Edit

Everything View permits, plus every tool that changes a project — building and changing edits, transcripts, media and exports.

Access is a ladder — none, then view, then comment, then edit — and a call is allowed when your level on that project is at least the level the tool needs. Someone who can comment therefore clears the view level and reaches every read-only tool, and never clears the edit level, so no tool that writes and no charge.

A call that needs a level you do not have is refused, and the refusal names the level it wanted. Ask the project owner to share it with you, or to turn on link access.

• The prompt never appears. Your client is probably configured for the wrong transport. It must be Streamable HTTP, not stdio.
• The client asks for a client id or a token. Leave those fields empty. Filling them in with an invented value is what breaks the flow.
• Every call comes back unauthorised after a working session. The token is no longer accepted. Disconnect the server in your client and connect it again, which runs the sign-in from the start.
• The host looks wrong. Use https://mcp.heyeddie.ai/api/mcp exactly. It is the identifier tokens are issued against, so a substituted host fails validation even when it serves the same application.

Failures that arrive after you are signed in are covered in Errors and limits.