HTTP and JSON-RPC

HTTP contract

Send a single JSON-RPC message per POST to APOB_MCP_URL. The current server supports MCP versions 2025-03-26, 2025-06-18, and 2025-11-25; the examples use 2025-11-25. Use the version returned by initialization for later requests.

Header or limit	Contract
`Authorization`	`Bearer <MCP_ACCESS_TOKEN>` from the OAuth flow.
`Content-Type`	`application/json`.
`Accept`	Include both `application/json` and `text/event-stream`.
`MCP-Protocol-Version`	Send the negotiated version on requests after initialization. Unsupported or duplicate values are rejected.
`Origin`	If supplied, exactly match the configured MCP resource’s scheme, host, and port. Duplicate or other origins are rejected.
Body size	At most 16 KiB; upload bytes directly using the upload flow.

The endpoint is stateless: it does not issue or require Mcp-Session-Id. GET and DELETE return 405; there is no standalone SSE subscription at /mcp. Successful request responses use JSON. Accepted notifications return 202 with an empty body. The Accept requirement follows the Streamable HTTP transport specification.

Initialize

curl "$APOB_MCP_URL" \
  -H "Authorization: Bearer $MCP_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"example-client","version":"1.0.0"}}}'

Inspect result.protocolVersion, result.serverInfo, and result.capabilities. APOB advertises tools and resources; it does not advertise prompts, tool-list change notifications, or resource subscriptions. Then send the notification:

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

Discover tools and call one

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Each tool supplies its name, description, inputSchema, and annotations. Generation schemas include account-specific defaults. Preserve schema conditions and explicit user choices; see the tool catalog. The tool name belongs in params.name, and its inputs in params.arguments:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_personal_models",
    "arguments": { "pageNumber": 1, "pageSize": 10 }
  }
}

Use a distinct JSON-RPC request ID to correlate each response. That ID does not make a creation or payment call idempotent.

Read the image prompt resource

resources/list exposes apob://docs/image-prompt-format/v1, a Markdown guide to the tagged prompt required by create_image. Read it before constructing a request; resource discovery alone does not insert its rules into a host’s prompt.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "apob://docs/image-prompt-format/v1" }
}

The response has result.contents entries with uri, mimeType, and text. Ordinary video and editing tools use their own prompt contracts rather than the create_image tags.

Results

Successful tool calls return result.structuredContent and the same JSON serialized into a text entry in result.content. Interpret the tool’s fields and isError before treating a call as successful. A generation receipt is an accepted submission; poll get_generation_result for finished media.

Errors

Layer	Examples	What to do
HTTP authentication	`401` with Bearer challenge for missing, invalid, expired, or revoked credentials; `403` for insufficient scope.	Inspect `WWW-Authenticate`, authorize the expected account, and request `mcp:access`.
HTTP request	`400` unsupported protocol version or invalid Accept header, `403` invalid Origin, `405` unsupported method, `413` oversized body, `415` non-JSON content type. Malformed JSON or unsupported methods can also fail at transport level.	Correct the request. Authentication can reject it before transport validation.
JSON-RPC	Top-level `error` for unknown tool/resource requests or tool-discovery account lookup failure.	Inspect the error and correct the request or retry a read as appropriate.
Tool	`result.isError: true` for input-schema validation or a tool’s public error code/message.	Follow the specific tool’s recovery guidance. HTTP `200` alone is not success.

An authentication storage outage fails closed with a retryable HTTP 503. A lost response or a transport failure after a write can leave the outcome uncertain. Follow generation errors or billing reconciliation, and do not automatically repeat paid work.

Get started

Core concepts

Workflows

MCP API

GraphQL API

Usage and troubleshooting

HTTP contract

Initialize

Discover tools and call one

Read the image prompt resource

Results

Errors

​HTTP contract

​Initialize

​Discover tools and call one

​Read the image prompt resource

​Results

​Errors

HTTP contract

Initialize

Discover tools and call one

Read the image prompt resource

Results

Errors