mcp-ToseaAI

Official MCP server for ToseaAI document-to-presentation workflows.

This server wraps the production ToseaAI HTTP contract at /api/mcp/v1 and exposes a stable MCP tool surface for Claude Code, Cursor, Codex, and other MCP clients.

• API keys stay server-side and are never echoed back to the agent.

• Long-running operations use presentation_id plus polling, not raw SSE.

• Mutating tools support explicit idempotency keys where the backend supports them.

• Export-capable tools accept an optional export_filename so downstream clients can receive a friendly attachment name.

• File uploads stay local until the MCP server streams them to ToseaAI over HTTPS.

Why a separate repo

This repository should stay independent from the main application repository.

• Release cadence is different from the backend.

• Breaking changes to tool names and prompts must be versioned separately.

• Nested git repos or submodules add unnecessary operational friction for MCP users.

Install

npm install
npm run build

Required environment variables

TOSEA_API_KEY=sk_...
TOSEA_API_BASE_URL=https://tosea.ai

Optional:

• TOSEA_TIMEOUT_MS

• TOSEA_MAX_RETRIES

• TOSEA_MAX_TOOL_CONCURRENCY

• TOSEA_MAX_MUTATING_CONCURRENCY

• TOSEA_MAX_PENDING_TOOL_REQUESTS

• TOSEA_POLL_INTERVAL_MS

• TOSEA_MAX_POLL_MS

• TOSEA_LOG_LEVEL

Claude Code example

{
  "mcpServers": {
    "tosea": {
      "command": "node",
      "args": ["C:/new/mcp-ToseaAI/dist/src/index.js"],
      "env": {
        "TOSEA_API_KEY": "sk_...",
        "TOSEA_API_BASE_URL": "https://tosea.ai"
      }
    }
  }
}

Client-specific examples live in examples/README.md.

Cursor example

Use examples/cursor.mcp.json as the starting point for your local mcp.json.

OpenAI Agents SDK example

OpenAI's Agents SDK supports stdio MCP servers, so this repo can be used directly as a local subprocess MCP without needing a hosted HTTP wrapper. See examples/openai-agents-typescript.ts.

If you later need OpenAI Responses API hosted remote MCP mode, add a separate Streamable HTTP transport wrapper instead of changing this stdio package in place.

Tool summary

• tosea_health

• tosea_get_permissions_summary

• tosea_get_quota_status

• tosea_list_presentations

• tosea_get_presentation_full_data

• tosea_switch_template

• tosea_create_document_parse

• tosea_get_document_parse

• tosea_wait_for_document_parse

• tosea_get_document_parse_result

• tosea_parse_pdf

• tosea_generate_outline

• tosea_edit_outline_page

• tosea_render_slides

• tosea_edit_slide_page

• tosea_export_presentation

• tosea_pdf_to_presentation

• tosea_wait_for_job

• tosea_list_exports

• tosea_list_export_files

• tosea_redownload_export

Reliability model

• GET requests use bounded retries with backoff and jitter.

• Read-only tools use singleflight coalescing for identical in-flight requests, so repeated concurrent calls like the same list_presentations query are collapsed into one upstream request.

• All tools use bounded local concurrency inside one MCP server process; once the local queue is full, the MCP server returns a retryable backpressure error instead of letting requests pile up until transport-level failure.

• Mutating tools are locally gated with bounded concurrency, and writes for the same presentation_id are serialized inside one MCP server process.

• Upload-creating endpoints (pdf-parse, pdf-to-presentation) accept idempotency_key, but the MCP server still avoids silent auto-retries for large uploads by default.

• outline edit, slide edit, and export support idempotency_key; reuse the same value only when retrying the same logical action.

• tosea_export_presentation and tosea_pdf_to_presentation accept optional export_filename when the visible exported attachment name matters.

• tosea_create_document_parse is the standalone Markdown/asset extraction facade. It returns document_parse_id and still uses the backend's existing auth, quota, and billing rules.

• tosea_parse_pdf remains the staged presentation parse step for workflows that continue into outline generation and slide rendering.

• wait_for_job follows nested data.job.status when the backend reports a separate export/full job, and falls back to top-level presentation status when no nested job exists.

• html_zip export is supported for HTML-mode decks and remains a free export on the backend.

• Stdio lifecycle is tied to the host process: the server shuts down on stdin close, SIGINT, and SIGTERM, and unexpected transport failures are surfaced as retryable host-transport errors instead of opaque raw exceptions.

Attachment delivery

If an MCP client downloads a finished export and then relays it through OpenClaw, WeChat, email, or another chat surface:

• pass export_filename when the user cares about the final visible attachment name

• preserve filename, extension, and Content-Type when re-uploading the artifact

• do not repackage the file as an anonymous binary attachment, or downstream clients may show only a generic attachment label

Asset file_id inputs

• logo_file_id is the file_id of a previously confirmed uploaded logo asset. It is not a local path.

• template_file_id is the file_id of a previously confirmed uploaded PPTX/PDF custom-template asset. It is not a source document path.

• template_file_id is valid only with slide_mode="image".

• When template_file_id is present, the backend treats the request as custom_template automatically.

• This MCP package does not mint those asset IDs itself yet. Reuse IDs created through the scripts-first skill or another upload-capable product flow.

Upload constraints

• page_count_range must be one of 4-8, 8-12, 12-16, 16-20, 20-30, 30-40, 40-50, or 50-100.

• Source-file count and total source-page limits are enforced by backend tier policy.

• The current default/free backend policy is 1 source file and 60 total source pages unless the server-side policy overrides it.

Image mode decision rule

• keep slide_mode="html" by default

• use slide_mode="image" only when the user explicitly wants image-mode rendering or image-first slide composition

• when using image mode, pass image_model if the user cares about image quality or regeneration consistency

• use output_format="pptx_image" when the user wants a pure image-based PPTX export

• use output_format="pdf" for image-mode review handoff

• do not use output_format="html_zip" for image-mode decks

Security notes

• API keys must start with sk_.

• The server redacts bearer secrets from surfaced errors.

• The MCP tool layer does not expose JWT-only account operations.

• Export history only exposes user-visible files returned by the backend.

Smoke test

This repository includes a non-billing smoke test that checks auth, health, permissions, and list access without creating presentations:

npm run smoke

Optional flags:

• --feature-key outline_generate

• --expect-tier pro

• --list-limit 5