MCP Server Architecture
Understand how OpenSana exposes an MCP server over the Convex HTTP layer.
OpenSana exposes an MCP server through a Convex HTTP endpoint.
What It Does
The MCP server allows external tools such as editors and AI agents to:
- list projects
- inspect tasks
- create or update work
- manage task artifacts and comments
High-Level Flow
- client sends JSON-RPC over HTTP
- API key authenticates the user
- project scope is resolved from URL and tool arguments
- handler validates params and dispatches to Convex APIs
Important Boundary
The MCP server is not the same thing as the CLI thread execution loop:
- MCP is request-response
- CLI thread execution is long-running, claim-based, and streaming
Source Material
The internal source of truth for detailed behavior currently lives in docs/specs/mcp-server.md.