HTTP, MCP and sign-in

For: developers connecting an HTTP or MCP client. Start with Agent API and AI clients.

AI is optional. You confirm invoice issuance in Pepper.

Transport and access

Use the HTTPS scheme and host/port from APP_URL. Use the addresses shown in Settings > Agent connections.

Send Authorization: Bearer <credential> on every tool request. Cookies and URL parameters do not authenticate calls.

HTTP requests need Accept: application/json. POST and PUT bodies need Content-Type: application/json.

Requests with an Origin header fail. Call the HTTP API from a server or command-line client.

A connection acts as one active, non-guest user. Its grants do not add missing user permissions. Record access remains subject to that user's scope.

Responses use Cache-Control: no-store. Document and customer lists return data and next. Send next as the next request's after cursor.

A null cursor means the last page. These cursor lists order by ID and disclose no total count.

When demo mode is on, draft writes and invoice issue requests return 403. Permitted reads and previews remain available.

MCP transport

The MCP server address ends in /mcp. It accepts Streamable HTTP POST requests and returns JSON responses.

Use a remote MCP client with JSON responses. This server has no standalone event stream. GET and DELETE return 405 when access is on.

Send one JSON-RPC request or notification per call. JSON arrays and client responses fail. Notifications return 202 with no body.

Authenticate with a pasted connection credential or browser sign-in. Browser sign-in uses the separate owner-controlled switch in Agent connections.

The server supports tool discovery and calls. It does not expose MCP resources or prompts. Use tools/list for the granted tool schemas.

MCP names replace dots with underscores. For example, documents.get becomes documents_get.

For a record-specific MCP call, put id in the arguments. For a writing call, also put idempotency_key in the arguments.

HTTP puts the record ID in the path and the idempotency key in the Idempotency-Key header.

Successful MCP calls return structuredContent with the same data as HTTP. Tool failures set isError and include structured error data.

Authentication and protocol failures can return an HTTP error with a JSON-RPC error. They do not use the tool-result envelope.

Browser sign-in

Browser sign-in uses authorization code flow with PKCE S256. The owner checks the client and return address before allowing access.

Discovery identifies {APP_URL}/mcp as the resource. Send that resource when starting authorization or exchanging and refreshing tokens.

An unknown client or unregistered return address gets an error page. Made with Pepper does not redirect that request.

Public clients can use dynamic registration or a supported HTTPS Client ID Metadata Document. Registered clients need 1–5 return addresses.

Return addresses use HTTPS, or HTTP on localhost, 127.0.0.1 or [::1]. They must match the registered address and contain no fragment.

Authorization codes last 5 minutes and permit one exchange. Access tokens last up to 1 hour, limited by the connection's expiry.

Refresh tokens rotate. Reusing a code or a rotated refresh token revokes its connection. A refresh token never authenticates a tool call.

Registration, token and revocation requests have a 16 KiB body limit. Registration allows 10 requests per minute per IP address.

Token and revocation requests share a limit of 30 per minute per IP address. OAuth errors use error, such as invalid_grant.

Follow the client's sign-in flow for ordinary setup. See Connect through browser sign-in.