Transport Modes

Transport Modes

KPainter MCP currently supports two transport modes:

• stdio
• Streamable HTTP

stdio

This is the best fit for local MCP clients such as:

• Claude Desktop
• Cursor
• Cline
• Codex CLI

Start it with:

kp-mcp

Or run it from the kgp-service source tree:

python -m src.mcp_server

Use stdio when:

• the MCP client runs on your own machine
• you want the simplest setup
• you prefer passing the API key through environment variables

Streamable HTTP

This is the better fit for:

• remote agent hosts
• managed MCP platforms
• clients that expect an HTTP MCP endpoint

Run it directly with:

uvicorn src.mcp_server:app --reload --port 8002

By default, the standalone app exposes MCP at:

http://127.0.0.1:8002/mcp

If MCP is mounted inside the main KPainter API service, the default path is still:

/mcp

That means the MCP endpoint usually lives on the same API host as OpenAPI, but under /mcp instead of /openapi/v1.

Browser Considerations

The server already includes the minimum HTTP support that browser experiments would need:

• PARTNER_MCP_ALLOWED_ORIGINS
• Mcp-Session-Id exposed through CORS

But browser direct-connect is still not the recommended default path.

The current product recommendation is:

• normal pages: keep using REST / OpenAPI
• external agent platforms and IDEs: use MCP

Which Mode To Pick

• choose stdio for local development and desktop MCP clients
• choose Streamable HTTP for hosted or remote MCP environments

If you are unsure, start with stdio first. It is easier to debug and keeps auth handling simpler.