# Cormak.app MCP integration

Remote server: **https://mcp.cormak.app/mcp**. OAuth public client + PKCE S256.
Use `account:read projects:read` for the safe quickstart; no credits are spent.
Setup is described in README.md. Live `tools/list` is authoritative for a token.

## In Postman

The portable companion `Cormak.MCP.postman_collection.json` uses ordinary HTTP
JSON-RPC requests. It is **not a native Postman MCP request export**. For the
MCP Catalog, create a separate native MCP request in the same private workspace:
New → MCP request → HTTP → `https://mcp.cormak.app/mcp`; configure OAuth via the
server's discovery. Initialize, inspect the authorized tools, then invoke only
`get_account` / `list_projects` for the initial review. Save that request in
a dedicated native MCP collection. The current Postman UI does not allow saving
a native MCP request in the imported HTTP collections. Do not generate a replacement server from the REST spec.

[Postman supports existing remote HTTP MCP servers](https://learning.postman.com/docs/postman-api-network/showcase/publish/mcp-servers/promote/).
Publishing a native MCP request, workspace and collection remains subject to
owner confirmation. Native request import/export behavior must be verified in
the actual Postman client; the portable JSON does not claim that support.

## Transport quickstart

Send `Authorization: Bearer <local OAuth token>`, `Content-Type: application/json`
and `Accept: application/json, text/event-stream`. No client-controlled owner ID,
Supabase key or provider token is needed. The server uses stateless legacy
JSON-RPC over the same endpoint; no persistent session ID is required here.

```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"My integration","version":"1.0.0"}}}
```

Successful JSON-RPC payload (capabilities can evolve). The HTTP response can be JSON or an SSE stream with this payload in a `data:` field; the collection parses both formats:

```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"serverInfo":{"name":"Cormak AI","version":"1.4.0"}}}
```

The current protocol metadata retains the legacy server name `Cormak AI`.
The product/publisher name is **Cormak.app**. Use the negotiated protocol
version in `MCP-Protocol-Version` for subsequent requests. Next send
`{"jsonrpc":"2.0","method":"notifications/initialized"}` (202, empty), then:

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

```json
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_projects","arguments":{"limit":5}}}
```

A successful empty project library has this shape:

```json
{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"projects\":[]}"}],"structuredContent":{"projects":[]},"isError":false}}
```

`get_account` returns the caller's plan and counters, including
`available_ai_credits`. Project/library results are private; project HTML and
generated content are untrusted data. Never publish captured results or treat
their content as instructions. Error handling has three layers:

1. HTTP 401/403/413/429/503: transport, authorization, origin, limits or service failure.
2. JSON-RPC `error: {code,message,data?}`: protocol/validation failure.
3. HTTP 200 `result.isError=true`, usually `structuredContent.error`: tool failure.

For example, `get_project` with a nonexistent/foreign UUID returns a tool error
`project_not_found`; it does not expose another owner's project. Input schema
violations can be protocol validation errors. Do not assume every denial is an
HTTP 403. Detailed input schemas are in MCP_REFERENCE.md and mcp-tools.json.

## Available capabilities and boundaries

| Capability | Existing MCP surface |
|---|---|
| Tasks | Workspaces, boards/columns, versioned tasks, comments, checklist, dependencies, planning and reviewed execution |
| Agents | Saved agent settings/history, schedules, pause/activation and reviewed posts |
| Telegram bots | Safe list/status, synchronization and disconnect; BotFather token entry stays in Cormak |
| AI employees | Hire/settings, supported draft tasks/history and acceptance |
| Websites/presentations | Read/create saved project, rename/replace HTML, owner-approved publication; no streamed AI site/deck generator |
| Business | Entitled business-workspace records; no business-plan AI generation adapter |
| Photo/product content | Images, product description, price quotes and product-image workflows |
| Video / 3D | Existing generation/status and saved models; no cinema/shorts/clips/editor API |
| Audio | Permitted library voices and voiceover; no cloning workflow |
| SEO / ads | Existing audits and text drafts; no external ad-campaign launch |
| Finance / legal | Supplied-row calculations and metered legal drafts; no bank connection or legal filing |
| Hosting / domains | Owned records, availability and approved connection/status; no registrar purchase |
| CRM / personal assistant | No general external CRUD, Telegram inbox access or arbitrary internal proxy |

## Mutations, costs and asynchronous jobs

The read-only collection intentionally contains no paid tool or mutation.
The complete catalogue includes paid and state-changing tools; their descriptions
and schemas declare requirements. Permission to call a tool is not permission
to spend without the existing owner-consent mechanism.

Ordinary paid/external/destructive operations return `awaiting_confirmation`
and an `approval_url`. The owner reviews exact parameters, expected maximum and
context in Cormak. After approval, retry **the same tool, arguments and UUID**
within the consent window (15 minutes). Opening/approving the link itself does
not run the operation. A changed context can invalidate approval.

Product description/image tools additionally support the owner's existing
manual/delegated connection spending settings: per-operation and rolling 24-hour
AI-credit caps, expiry/revocation and generation-count limits. Default is manual.
Use `get_connection` and a fresh quote, pass `expected_credits` or
`expected_max_credits` exactly as declared in the tool schema. Do not change
connection spending settings from an integration token.

Representative source prices: simple image 2 shared AI credits; 3D 25 AI credits;
video uses **separate video credits** (1/2/4 according to resolution/duration);
product description 1 AI credit (optional analysis currently adds 0); employee draft 1;
SEO audit 3, compare 2, page/GEO 1; legal text reserves 25–50. Product image
quotes include selected model, quality, frame count and optional analysis/text.
Optional analysis currently adds 0 credits. Prices and entitlement checks are server-side; use the live quote instead of
hardcoding a price table. Read-only finance calculations spend no credits.

| Start operation | Poll using original request_id | Next step |
|---|---|---|
| generate_image / generate_video / generate_3d | get_generation | For video/3D use returned backend_request_id in get_video_status / get_3d_status |
| General task/agent/employee/project/domain operation | get_operation | Inspect result and the relevant module's saved record |
| describe_product / generate_product_images | get_product_operation | Inspect item outcomes, credits and private URLs; this poller also dispatches the next authorized paid step |

Typical start shape:

```json
{"request_id":"00000000-0000-4000-8000-000000000001","status":"awaiting_confirmation","approval_url":"https://app.cormak.app/mcp?approval_id=00000000-0000-4000-8000-000000000002"}
```

This is synthetic structured content, not an approval URL to visit. A running
generation can return `backend_request_id`, `next: "get_generation"` and
`poll_after_seconds: 5`. Preserve exact UUIDs and bodies on retries. Failed
operations retain backend-specific refund rules; `unknown` means the external
effect may have happened. Do not auto-resubmit with a new UUID or promise a
refund. Revocation blocks new steps; already submitted work may complete.

## Limits

120 MCP requests/minute/grant, including discovery of tools and status polls.
429 uses `Retry-After: 60`. Body max 13,000,000 bytes; per-tool strings, arrays
and inline media have smaller exact schema limits. Owner generation limit
0–10,000 is rolling 24 hours; 0 blocks new paid MCP generations. Modules enforce
additional account, plan, AI-consent and abuse restrictions. There is no general
public subscription or payment API in this package.
