MCP Server

The vivenu MCP server lets AI clients such as Claude, ChatGPT, Cursor and Codex read and change data in a vivenu account through the Model Context Protocol. The server URL is https://agents.vivenu.com/api/mcp.

MCP clients authenticate with OAuth 2.1, using the authorization code flow with PKCE as defined in the MCP specification. A client acts on behalf of the signed-in dashboard user and has the same permissions as that user. API keys and organization accounts are not supported.

Send the access token in an Authorization header with a Bearer prefix. Requests without a valid token fail with 401 Unauthorized. The WWW-Authenticate header of that response points to the protected resource metadata.

Discovery

The protected resource metadata names the dashboard as the authorization server:

GET https://agents.vivenu.com/.well-known/oauth-protected-resource

{
  "resource": "https://agents.vivenu.com/api/mcp",
  "authorization_servers": ["https://dashboard.vivenu.com"],
  "bearer_methods_supported": ["header"]
}

The authorization server metadata lists the endpoints and supported features:

GET https://dashboard.vivenu.com/.well-known/oauth-authorization-server

{
  "issuer": "https://dashboard.vivenu.com",
  "authorization_endpoint": "https://dashboard.vivenu.com/oauth2/authorize",
  "token_endpoint": "https://vivenu.com/api/oauth2/token",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "client_id_metadata_document_supported": true
}

Client identification

MCP clients do not register with vivenu and have no client secret. The client_id is the HTTPS URL of a Client ID Metadata Document. Dynamic client registration is not supported.

vivenu fetches the document and accepts it only if all of the following apply:

  • The URL has no query string or fragment.
  • The host is on the vivenu allowlist of supported AI clients and does not resolve to a private IP address.
  • The client_id in the document matches the URL it was fetched from.
  • token_endpoint_auth_method is none or missing.
  • redirect_uris is a non-empty list. The redirect_uri of each request must match one of them.

Authorization

The client sends the user to https://dashboard.vivenu.com/oauth2/authorize with response_type=code, client_id, redirect_uri, code_challenge, code_challenge_method=S256 and an optional state. The user signs in to the dashboard and approves access for the account they are signed in to.

vivenu then redirects to redirect_uri with code and state query parameters. The code expires after 10 minutes.

Tokens

The client exchanges the code at POST https://vivenu.com/api/oauth2/token. The endpoint accepts application/json and application/x-www-form-urlencoded.

  • grant_type: authorization_code — send code, client_id, redirect_uri and code_verifier. client_id and redirect_uri must match the authorization request.
  • grant_type: refresh_token — send refresh_token and client_id.

Both return the same response:

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "6f1c0e...",
  "token_type": "Bearer",
  "expires_in": 900
}

Expiration

Access tokens are valid for 15 minutes. Refresh tokens are valid for 7 days.

Each refresh token can be used once, and every refresh returns a new one. If a used refresh token is sent again, vivenu revokes every refresh token issued from the same authorization.

Was this page helpful?