Jun 27, 2025
Bring your own technical assistant everywhere


If you've been anywhere near AI developer tools recently, you've probably heard whispers (or shouts) about MCP - the Model Context Protocol. For those who haven't been following every announcement, MCP is an open protocol that enables AI assistants to safely interact with external tools and data sources. Think of it as a standardized way for AI to use tools, just like REST APIs standardized how applications talk to each other.
At kapa.ai, we've been helping teams build RAG-powered technical assistants that answer questions from their documentation, community forums, support tickets, and other knowledge sources. Our platform typically surfaces through web chat widgets, Slack bots, or API integrations. But what if your Kapa assistant could meet developers exactly where they work - in their IDEs, AI coding assistants, or desktop applications?
That's exactly what we built for our internal team, and now we're sharing how you can do the same.
The Power of Kapa + MCP
Imagine this: You're deep in your codebase using Cursor or Claude Desktop, and instead of context-switching to your documentation site or Slack to ask a question, you simply have your AI assistant do it for you. Behind the scenes, it queries your Kapa project, which already knows everything about your product, APIs, and documentation. No context switching. No hunting through docs. Just answers, right where you need them.

Our internal engineering team has been using this setup, and it's transformed how we work. Questions like "How do I configure OAuth for our API?" or "What's the rate limit for the search endpoint?" get instant, accurate answers without leaving the IDE.
Understanding the Architecture
When building an MCP server for Kapa, you have two main deployment patterns to choose from:
1. Authless Servers: Simple and Open
Perfect for:
Open source projects where documentation is public
Supporting your end-users and external developers
Quick proof-of-concepts and experiments
Note: Authless servers mean anyone with the server URL can query your Kapa instance. While simple to implement, consider rate limiting to prevent unexpected usage spikes that could lead to overages.
2. Authenticated Servers: Secure and Controlled
Ideal for:
Internal teams accessing proprietary documentation
Support agents who need access to internal knowledge bases
Scenarios where you need usage tracking per user
Protecting sensitive documentation or limiting access
The authenticated approach adds OAuth 2.1 to the mix, creating a secure boundary around your Kapa knowledge base.
Prerequisites and Setup
Before diving into code, let's gather what you'll need from the Kapa platform:
1. API Key
On the Kapa dashboard, navigate to **API Keys** and create a new API key. This key authenticates your MCP server with Kapa's API.
2. Project ID
Grab your project ID - it's the UUID in the address bar when you're on the Kapa dashboard. The project ID tells Kapa which knowledge base to query.
3. Integration ID
Create a new integration in your Kapa dashboard. This unique identifier helps you track usage analytics for your MCP server separately from other integrations. Give it a memorable name, like "Remote MCP server", to help distinguish it from other integrations.
Development Environment
For this tutorial, we'll use the amazing resources provided by the folks over Cloudflare, which makes building and deploying a remote MCP server a breeze.
A Cloudflare account (free tier works great)
Node.js and npm installed locally
Basic familiarity with JavaScript (though our examples are easy to follow)
Building an Authless MCP Server
Let's start with the simpler approach - an authless server that anyone can use to query your Kapa instance.
Step 1: Clone the Starter Template
In your terminal, run the following command to bootstrap an MCP server project for deploying on Cloudflare.
Step 2: Configure Your Kapa Integration
Update the MyMCP
class in src/index.ts
with your Kapa-specific implementation. The following example adds two tool calls:
ask_acme_question
: ask a question from your Kapa projectsearch_acme_sources
: retrieve relevant documents from the sources you've connected to your project
Copy and paste the following snippet, and replace all references to "acme" with the name of your product or service:
Step 3: Configure Environment Variables
Create a the Kapa secrets in Cloudflare:
Step 4: Deploy to Cloudflare
Your server will be available at https://my-mcp-server.<your-subdomain>.workers.dev/sse
Step 5: Test Your Server
Use the MCP Inspector to verify everything works:
Open the localhost address where the MCP inspector is running in your browser. Enter your server URL and test the tools. You should be able to list the available tools, ask questions, and search your documentation!
Integration with Development Tools
Once your MCP server is deployed, it's time to connect it to your tools:
Claude Desktop
Claude Desktop now lets you set up remote MCP servers as custom integrations in the Claude Desktop settings menu. Instructions here.
You can also add it manually, using the Claude Desktop configuration file:
Cursor
For Cursor, combine the command and arguments:
Troubleshooting Tips
Connection Issues: Ensure your server URL includes the `/sse` endpoint
Authentication Errors: For authenticated servers, verify your GitHub OAuth app settings
No Results: Check that your API key has the correct permissions in Kapa dashboard
Best Practices and Considerations
Building an Authenticated MCP Server
For teams needing access control and user tracking, the authenticated approach adds GitHub OAuth to secure your Kapa instance.
Rather than walking through the complex OAuth implementation here, check out the complete example from Cloudflare.
The key difference from the authless version is that this version uses an OAuth flow via GitHub to authenticate users before accessing Kapa tools, and restricting access to specific GitHub usernames.
Security First
API Key Management: Never commit API keys to version control. Use appropriate secrets management tools to store credentials
Rate Limiting: For public servers, consider implementing request throttling to prevent abuse and unexpected costs
Analytics and Monitoring
One of Kapa's strengths is its built-in analytics. By using a unique Integration ID for your MCP server, you can:
Track usage patterns specific to IDE-based queries
Understand what documentation gaps developers face
Monitor query volume and performance
Identify opportunities to improve your documentation
Access these insights in your Kapa dashboard and filter for [your MCP integration name].
Conclusion
Building an MCP server for Kapa transforms how teams interact with their documentation. Whether you choose the simplicity of an authless server or the control of an authenticated one, you're giving your team superpowers - instant access to your collective knowledge, right where they work. If you have a public-facing Kapa deployment, start with an authless server to experience the workflow benefits, then consider authentication as your needs grow. The beauty of this approach is its flexibility - you can have multiple MCP servers for different use cases, teams, or access levels.
Next Steps
1. Start Simple: Build an authless server for your public documentation
2. Experiment: Try different tool configurations and prompts
3. Share Feedback: Let us know what you build! Reach out to the Kapa team if you need help brainstorming ideas or run into challenges
Resources
Happy building! 🚀

Turn your knowledge base into a production-ready AI assistant
Request a demo to try kapa.ai on your data sources today.