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.

npm create cloudflare@latest -- my-mcp-server --template=cloudflare/ai/demos/remote-mcp-authless
cd my-mcp-server

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 project

• search_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:

export class MyMCP extends McpAgent<Env, Record<string, never>, Props> {
  server = new McpServer({
    name: "Acme, Inc. MCP Server",
    version: "0.0.1",
  });

  // Store API configuration
  private apiKey: string = "";
  private projectId: string = "";
  private integrationId: string = "";
  private baseUrl = "https://api.kapa.ai";

  constructor(state: DurableObjectState, env: Env) {
    super(state, env);
    // Initialize API configuration from environment variables
    this.apiKey = env.KAPA_API_KEY || "";
    this.projectId = env.KAPA_PROJECT_ID || "";
    this.integrationId = env.KAPA_INTEGRATION_ID || "";
  }

  async init() {
    // Tool for askign technical questions about ACME
    this.server.tool("ask_acme_question", { query: z.string().describe("The question about ACME to ask") }, async ({ query }) => {
      try {
        const response = await fetch(`${this.baseUrl}/query/v1/projects/${this.projectId}/chat/`, {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
            "X-API-KEY": this.apiKey,
          },
          body: JSON.stringify({
            integration_id: this.integrationId,
            query: query,
          }),
        });

        if (!response.ok) {
          return {
            content: [
              {
                type: "text",
                text: `Error: kapa.ai API returned ${response.status} - ${response.statusText}`,
              },
            ],
          };
        }

        const data = (await response.json()) as { answer?: string; thread_id?: string; question_answer_id?: string };
        return {
          content: [
            {
              type: "text",
              text: data.answer || "No answer received",
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Error: Failed to call kapa.ai API - ${error instanceof Error ? error.message : String(error)}`,
            },
          ],
        };
      }
    });

    // Search tool for retrieving documentation from Kapa
    this.server.tool(
      "search_acme_sources",
      {
        query: z.string().describe("The search query to find relevant ACME documentation"),
      },
      async ({ query }) => {
        try {
          const response = await fetch(`${this.baseUrl}/query/v1/projects/${this.projectId}/search/`, {
            method: "POST",
            headers: {
              "Content-Type": "application/json",
              "X-API-KEY": this.apiKey,
            },
            body: JSON.stringify({
              query: query,
            }),
          });

          if (!response.ok) {
            return {
              content: [
                {
                  type: "text",
                  text: `Error: kapa.ai API returned ${response.status} - ${response.statusText}`,
                },
              ],
            };
          }

          const data = await response.json();
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(data, null, 2),
              },
            ],
          };
        } catch (error) {
          return {
            content: [
              {
                type: "text",
                text: `Error: Failed to call kapa.ai API - ${error instanceof Error ? error.message : String(error)}`,
              },
            ],
          };
        }
      },
    );
  }
}

Step 3: Configure Environment Variables

Create a the Kapa secrets in Cloudflare:

npx wrangler secret put KAPA_API_KEY
npx wrangler secret put KAPA_PROJECT_ID
npx wrangler secret put KAPA_INTEGRATION_ID

Step 4: Deploy to Cloudflare

npm run deploy

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:

npx @modelcontextprotocol/inspector@latest

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:

{
  "mcpServers": {
    "query_acme": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-server.workers.dev/sse"]
    }
  }
}

Cursor

For Cursor, combine the command and arguments:

{
  "mcpServers": {
    "query_acme": {
      "command": "npx mcp-remote https://your-server.workers.dev/sse"
    }
  }
}

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 by filtering 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

• kapa.ai API Documentation

• Cloudflare: Build a Remote MCP Server

• MCP Protocol Specification

Happy building! 🚀