Connect to the Elocuenti MCP server

Endpoints

MCP endpoint

https://mcp.elocuenti.com/mcp

Protected resource metadata

https://mcp.elocuenti.com/.well-known/oauth-protected-resource

Authorization server metadata

https://mcp.elocuenti.com/.well-known/oauth-authorization-server

Client registration (RFC 7591)

POST https://mcp.elocuenti.com/register

Authorization

GET https://mcp.elocuenti.com/authorize

Token

POST https://mcp.elocuenti.com/token

Revocation (RFC 7009)

POST https://mcp.elocuenti.com/revoke

Register a client

Register once with POST /register (Dynamic Client Registration) and declare how your client authenticates at the token endpoint:

• client_secret_post or client_secret_basic — a confidential client, such as a backend. The response carries a client_secret once; we only keep its hash. This is the default when you omit the field.
• none — a public client that cannot keep a secret, such as a desktop or browser app. No secret is issued.

Any other method is rejected.

Authorize

Use the authorization code flow with PKCE (S256, required) and send resource=https://mcp.elocuenti.com/mcp (RFC 8707). The business owner signs in with their Elocuenti user and picks which businesses the client may act on. At /token, a confidential client must authenticate with its secret on every grant.

Tokens and how long they live

• Access token: a Bearer JWT valid for 15 minutes.
• Refresh token: valid for 30 days since its last use. A session that keeps refreshing never expires.
• Access is re-checked on every refresh: roles changed in Elocuenti apply at the next refresh, and a user who lost access to every business they authorized gets their session ended.

Confidential clients: the refresh token does not change

When the client authenticates with its secret, every refresh returns the same refresh token and extends it 30 days. Several workers can refresh at the same time without invalidating each other. Without the secret the token is useless.

Public clients: the refresh token rotates

Every refresh returns a new refresh token and spends the one you sent. Always store the latest one.

• Grace window of 60 seconds. If the same client presents a token within 60 seconds of its rotation (two workers racing), we issue one more valid token instead of treating it as an attack. A third use inside the window is rejected with Refresh token invalid, and the session stays alive.
• Reuse outside the window ends the session. Presenting a spent token later, or from another client, is treated as token theft (RFC 9700) and revokes every token of that session.

Errors

401 invalid_client — Client authentication failed

The client registered with a secret did not send it or sent the wrong one, or the client_id is unknown. Send client_secret in the body (client_secret_post) or with HTTP Basic (client_secret_basic), never both.

400 invalid_grant — Refresh token expired

It was not used for 30 days. The business owner has to connect again.

400 invalid_grant — Refresh token revoked

The session was ended: revoked through /revoke, or a token of the same session was reused and the whole session was closed.

400 invalid_grant — Ya no tienes acceso a los Negocios que autorizaste. Pide acceso a un administrador y vuelve a conectar.

The user no longer has access to any business they authorized (Spanish text, as returned). An administrator has to grant access again before reconnecting.

400 invalid_grant — Detectamos un uso repetido de tus credenciales y cerramos la sesión por seguridad. Vuelve a conectar tu cuenta.

Reuse detected (Spanish text, as returned): a public client presented a refresh token that had already been rotated, outside the grace window or from another client. We treat it as token theft and end the whole session. Connect again, and refresh from one process at a time.

400 invalid_grant — Refresh token invalid

We did not issue this token to this client, or it is a third use of the same spent token inside the grace window (the session stays alive: use the latest refresh_token you stored).

503 temporarily_unavailable

A transient failure on our side. Your tokens are still valid: retry with backoff and never discard credentials on a 5xx.

Server-to-server integrations

1. Register as confidential (client_secret_post) and keep the secret on your server. Your refresh token then stays the same.
2. Refresh from one process at a time if you use a public client, and always persist the refresh token we return.
3. Retry 503s with backoff. Only an invalid_grant or invalid_client means the business owner has to connect again.

Support

Questions about connecting to the MCP server? Write to contacto@elocuenti.com.