---
title: "Hosted MCP server (stateless Streamable HTTP)"
method: POST
path: "/credits/mcp"
tags: ["MCP"]
---

# Hosted MCP server (stateless Streamable HTTP)

`POST /credits/mcp`

## Request

- Base URL: `https://api.paywithlocus.com/api`
- URL: `https://api.paywithlocus.com/api/credits/mcp`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://api.paywithlocus.com/api/credits/mcp/oauth/authorize`
    - Token URL: `https://api.paywithlocus.com/api/credits/mcp/oauth/token` scopes: `mcp:read`
  - HTTP bearer
  - HTTP bearer
  - HTTP bearer

One MCP JSON-RPC request per POST, with an encoded JSON body limit of 4 MiB. OAuth 2.1 is the primary authentication path: initialize, discovery, and resource reads require mcp:read, while billed tools/call execution additionally requires mcp:execute. Tenant secret keys, end-user JWTs, and scoped agent connections remain compatibility credentials. This transport is stateless: it issues no MCP-Session-Id, retains no resumable SSE stream, and recomputes the authenticated tenant catalog on every request. For tools/call, inspect result.isError even when HTTP and JSON-RPC both succeeded.

## Headers

- `X-Locus-Session-Id` string
- `MCP-Protocol-Version` string
- `Accept` string, required

## Request body

- McpJsonRpcRequest
  - `jsonrpc` '2.0', required
  - `id` union
    - string
    - number
  - `method` string, required
  - `params` object

## Response `200`

JSON-RPC success or protocol error. A tools/call application failure is a success envelope whose result.isError is true.

- union
  - McpJsonRpcSuccess
    - `jsonrpc` '2.0', required
    - `id` union, required
      - string
      - number
    - `result` union, required
      - McpToolCallResult: Success and application-failure result for tools/call. isError=true is failure even though the JSON-RPC promise resolved.
        - `content` union[], required
          - union
            - McpTextContent
              - …
            - McpImageContent
              - …
            - McpAudioContent
              - …
            - McpEmbeddedResource
              - …
        - `isError` boolean
        - `structuredContent` object: Typed success data and compact artifact/billing descriptors. Raw binary or oversized JSON is not duplicated here.
        - `_meta` McpLocusMeta
          - `locus/status` integer
          - `locus/creditsCharged` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
          - `locus/creditsBalance` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
          - `locus/costUsd` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
          - `locus/idempotencyKey` string
          - `locus/approvalId` string, uuid
          - `locus/maxChargeCredits` string: Non-negative exact decimal string with at most six fractional digits. Endpoint-specific positivity and amount limits still apply.
          - `locus/reapprovalRequired` boolean
          - `locus/artifact` McpArtifact
            - `uri` string, required
            - `mime_type` string, required
            - `byte_size` integer, required
            - `sha256` string, required
            - `filename` string, required
            - `disposition` 'inline', required
            - `expires_at` string, date-time, nullable, required
            - `download_url` string, uri: Signed link to the bytes. No bearer needed; it expires at expires_at.
            - `api_call_id` string
          - `locus/presentation` McpPresentation
            - `providerName` string, required
            - `actionName` string, required
            - `category` string, nullable, required
            - `description` string, required
            - `logoUrl` string, uri, nullable, required
            - `fallback` object, required: Stable monogram used when logoUrl is absent or fails.
              - …
            - `assetVersion` '1', required: Version token used in Locus-hosted logo URLs for cache invalidation.
            - `cacheControl` 'public, max-age=86400', required
            - `presentationOnly` unknown, required
      - object
  - McpJsonRpcError
    - `jsonrpc` '2.0', required
    - `id` union, required
      - string
      - number
    - `error` object, required
      - `code` integer, required: JSON-RPC/MCP protocol code, not a Locus billing status.
      - `message` string, required
      - `data` unknown

## Other responses

- `202`: Accepted MCP notification; no JSON-RPC response body.
- `400`: Malformed JSON-RPC or unsupported Streamable HTTP request
- `401`: OAuth authorization is missing or invalid, or a compatibility secret-key, end-user, or agent-connection credential is invalid. Sandbox and publishable keys are not accepted.
- `403`: The OAuth token lacks mcp:read or, for billed tools/call, mcp:execute; or an authenticated compatibility principal is denied by tenant, origin, or policy controls.
- `405`: POST is the only supported method; stateless sessions cannot be fetched or deleted
- `413`: Encoded JSON request exceeds the 4 MiB Locus Pro execution limit
- `500`: Request-scoped MCP transport failure

---

[API](https://skmtc.dev/paywithlocus/apis/locus-pro-api.md) - [All operations](https://skmtc.dev/paywithlocus/apis/locus-pro-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paywithlocus/apis/locus-pro-api/revisions/aab8fa5d6cef?raw)