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.

• 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_POLL_INTERVAL_MS

• TOSEA_MAX_POLL_MS

• TOSEA_LOG_LEVEL

Claude Code example

{
  "mcpServers": {
    "tosea": {
      "command": "node",
      "args": ["C:/new/mcp-ToseaAI/dist/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_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.

• Upload-creating endpoints do not auto-retry because the current backend does not accept idempotency keys on those routes.

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

• wait_for_job polls until completed or failed, then returns the final job payload as JSON.

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