Skip to main content

​
Architecture

The Leeroopedia MCP server is a thin client — it contains no search logic or knowledge base access itself. All intelligence lives on the backend.

​
Request Lifecycle

1

Agent calls a tool

Your AI coding agent calls a tool (e.g., search_knowledge) via the MCP protocol. The server validates the tool name and arguments.
2

Task created on backend

The MCP client sends POST /v1/search with the tool name and arguments. The backend queues the task and returns a task_id immediately.
3

Polling with exponential backoff

The client polls GET /v1/search/task/task_id with exponential backoff. Starts at 0.5 seconds, grows by 1.5x each iteration, caps at 5 seconds between polls, and times out after 300 seconds (configurable).
4

Results returned

When the task completes, the synthesized response is returned to your agent as TextContent, including PageID citations and remaining credits.

​
Why Async Tasks?

The backend runs AI agents that search the knowledge base from multiple angles, read relevant pages, and synthesize structured responses. This can take 10-60 seconds depending on the tool and query complexity. The async task pattern (create task, then poll) avoids HTTP timeouts and lets the backend agents take the time they need for thorough research.

​
Components

​
Transport

The server uses stdio transport (stdin/stdout), which is the standard for Claude Code and Cursor MCP integrations. Logging goes to stderr to avoid interfering with the MCP protocol on stdout.