Integrations
Connect ContextMCP to AI editors and custom agents
ContextMCP provides two ways to integrate:
- MCP Protocol - For AI editors (Cursor, Windsurf, Claude Desktop)
- REST API - For custom AI agents and applications
MCP Protocol
The Model Context Protocol is the standard way AI coding assistants fetch external context. Once you've deployed your ContextMCP server, connect it to your AI editor with the configuration below.
Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"my-docs": {
"url": "https://your-worker.workers.dev/mcp"
}
}
}Replace your-worker.workers.dev with your actual Cloudflare Worker URL. Restart Cursor to apply changes.
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"my-docs": {
"serverUrl": "https://your-worker.workers.dev/mcp"
}
}
}Replace your-worker.workers.dev with your actual Cloudflare Worker URL. Restart Windsurf to apply changes.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"my-docs": {
"command": "npx",
"args": ["-y", "mcp-remote@latest", "https://your-worker.workers.dev/mcp"]
}
}
}Replace your-worker.workers.dev with your actual Cloudflare Worker URL. Restart Claude Desktop to apply changes.
REST API
Use the REST API to integrate ContextMCP into your own AI agents, chatbots, or applications.
Endpoints
Search
GET /search?query=<text>&limit=<n>Parameters:
query(required): Natural language search querylimit(optional): Max results, default 5
Example:
curl "https://your-worker.workers.dev/search?query=how%20to%20authenticate&limit=3"Response:
{
"results": [
{
"score": 0.89,
"content": "## Authentication\n\nTo authenticate requests...",
"metadata": {
"source": "docs",
"path": "auth/overview.mdx",
"heading": "Authentication",
"url": "https://docs.example.com/auth/overview"
}
}
]
}Health Check
GET /healthReturns server status and version.
Using in Custom Agents
TypeScript Example
async function searchDocs(query: string): Promise<SearchResult[]> {
const response = await fetch(
`https://your-worker.workers.dev/search?query=${encodeURIComponent(
query
)}&limit=5`
);
const data = await response.json();
return data.results;
}
// Use in your agent
const context = await searchDocs("webhook signatures");
const completion = await openai.chat.completions.create({
messages: [
{ role: "system", content: `Use this context: ${JSON.stringify(context)}` },
{ role: "user", content: userQuestion },
],
model: "gpt-4",
});Embeddable Chat Widget (ContextChat)
Prefer a ready-made UI over wiring the API yourself? ContextChat is a drop-in "Ask AI" widget that streams cited answers from your ContextMCP backend. Deploy its Cloudflare Worker with RETRIEVAL_URL pointed at your ContextMCP /search endpoint (its default contextmcp adapter speaks this exact contract), then embed the widget on any page with one script tag:
<script>
window.ContextChat = {
chatEndpoint: "https://your-contextchat-worker.workers.dev/chat",
assistantName: "Docs Assistant",
starterQuestions: ["How do I authenticate?", "How do webhooks work?"],
};
</script>
<script src="https://your-contextchat-worker.workers.dev/widget.js" defer></script>See the ContextChat README for full setup and configuration.