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