Skip to main content
Connect to https://api.semicola.com/mcp/v3 with OAuth or an API key. The credential decides the home account, the accounts you can reach and what you may do in each. The URL does not select buyer or seller behavior. Grant only what the integration needs. A tool can appear in tools/list and still refuse a write when your role lacks the permission. After authenticating, call get_status to confirm the account.
An agent must never ask for a key in chat and cannot read an existing key back. Direct the person to Settings → API access in the Semicola app. A new key’s secret is shown once.

​
How OAuth works here

Semicola follows the MCP authorization spec. A compliant client needs only the endpoint URL.
1

Challenge

An unauthenticated request gets 401 and a challenge that points at the discovery document:
2

Discovery

The protected-resource document names the exact resource and its authorization server:
Follow the resource_metadata URL from the challenge rather than building it yourself, and read the authorization server from this document instead of hard-coding it. The authorization server’s own metadata is also mirrored at https://api.semicola.com/.well-known/oauth-authorization-server for clients that look on the resource’s origin.
3

Registration

Clients register themselves with dynamic client registration (RFC 7591) as public clients (token_endpoint_auth_method: none). Redirect URIs must use https; localhost is allowed.
4

Sign-in and consent

The client runs the authorization-code flow with PKCE (S256) and passes resource=https://api.semicola.com/mcp/v3. The person signs in on the Semicola login page, picks the account to connect if they have several, and approves the client. The browser then shows “Authentication complete” and hands control back to the client.
5

Tokens

The client receives a short-lived access token and a rotating refresh token, and sends Authorization: Bearer <access token> on every request.

​
Resource binding

Tokens are bound to the exact MCP URL they were issued for. Semicola checks the signature, issuer, expiry and that the token’s audience equals the URL being called. A token issued for /mcp/v3 is refused on the REST API, on the v2 endpoints and on per-seller AdCP endpoints. Carry the resource value through authorization, token exchange and refresh.

​
Seeing and revoking connections

Every OAuth client you approve appears under Settings → Connected apps with its name, when it first connected and when it last refreshed. Disconnect revokes its tokens immediately.

​
Errors you may see

MCP client setup

Host-specific configuration for Codex, Claude Code, Claude, ChatGPT and others.