Most MCP articles stop at "here are some MCP servers." This guide shows you how to use MCP as an interface to Keywords AI observability data (logs, traces, prompts, customers) inside coding assistants like Cursor and Claude Code.

---

Table of contents

1. Keywords AI MCP Server Overview
2. MCP Transport Protocols: HTTP vs stdio vs SSE
3. MCP Setup Modes: HTTP, stdio, and Private
4. Cursor MCP Setup
5. Claude Code MCP Setup
6. MCP Tools: Logs, Traces, Prompts & Customers
7. Debugging Workflows with MCP
8. MCP Observability & Tracing
9. MCP Architecture by Team Size
10. MCP Troubleshooting Guide

---

Keywords AI MCP Server Overview

Your Keywords AI MCP server is not “another tool integration.” It’s a bridge that lets your AI assistant query your observability system directly from the chat box / IDE. The docs say it plainly: it gives real-time access to Keywords AI logs, traces, prompts, and customer data in your coding environment.

So the mental model is:

• MCP client (Cursor / Claude Desktop / Claude Code)
• connects to
• Keywords AI MCP server
• which exposes tools like list_logs, list_traces, get_trace_tree, prompt/version fetchers, customer budget usage, etc.

This is why your blog shouldn’t read like “Top MCP servers.” It should read like: “Use MCP to turn your observability data into an assistant-native debugging workflow.”

---

MCP Transport Protocols: HTTP vs stdio vs SSE

Your docs call out two supported transports for the Keywords AI MCP server:

• HTTP streamable (recommended for hosted deployments)
• stdio (for local use)

Claude Code’s MCP docs add another concept you specifically asked about: SSE—but also says it’s deprecated in Claude Code and HTTP is preferred.

Let’s translate these into “what it means for developers.”

Streamable HTTP (the “production default”)

Streamable HTTP means the MCP server is reachable via an HTTP URL, and the transport supports streaming responses as they’re produced (instead of waiting for a single big response). Your hosted endpoint is:

• https://mcp.keywordsai.co/api/mcp

Why it’s the best default for Keywords AI MCP:

• No local install (just config + API key).
• Easier for teams to standardize
• Works well across machines, CI, remote dev environments
• Makes it straightforward to add “real observability” later (because you’re already on HTTP boundaries)

stdio (the “local process” transport)

stdio means your MCP “server” runs as a local process. The client launches it, writes requests to stdin, reads responses from stdout.

Your docs’ local setup is exactly that: clone keywordsai-mcp, build it, then configure Cursor/Claude to run node .../dist/lib/index.js with KEYWORDS_API_KEY in env.

Why devs choose stdio:

• Works offline / private local experiments
• Simple when you don’t want network endpoints
• Nice for hacking and iterating on MCP server code

Tradeoffs:

• Harder to roll out to a team consistently
• Harder to centrally observe (because every dev machine is its own “deployment”)

SSE (server-sent events): what it is, and why you should mostly avoid it now

SSE is a server→client streaming mechanism over HTTP. In MCP land, some clients historically supported “SSE MCP servers.”

But Claude Code explicitly says: SSE transport is deprecated and you should use HTTP servers instead where available.

Cursor community docs/examples often mention “stdio or sse” as transport options (depending on the server), but for Keywords AI specifically, your doc path is clearer:

• Use Streamable HTTP (hosted) for the normal path
• Use stdio when you truly need local/offline

---

MCP Setup Modes: HTTP, stdio, and Private

Your docs define three installation modes under “Installation”:

1. Public HTTP (Recommended)
2. Local Stdio
3. Private HTTP (Teams)

Here’s the practical framing (this is the part your audience cares about):

Mode A: Public HTTP (Recommended)

Use when: personal use, fastest setup, minimal maintenance.

Config is basically:

json
1{
2  "mcpServers": {
3    "keywords-ai": {
4      "url": "https://mcp.keywordsai.co/api/mcp",
5      "headers": {
6        "Authorization": "Bearer your_keywords_ai_api_key"
7      }
8    }
9  }
10}

That exact snippet is in your docs, along with Cursor + Claude Desktop config locations.

Mode B: Local stdio (you run it)

Use when: offline dev, you want to modify the MCP server, you’re testing.

The docs give the full flow: clone repo, npm install, npm run build, then configure the server as a local node command with env var KEYWORDS_API_KEY.

Mode C: Private HTTP (Teams)

Use when: you don’t want API keys on every laptop + you want one shared endpoint.

Your docs recommend deploying the MCP server (open source) to Vercel, storing KEYWORDS_API_KEY in Vercel env, then teammates use a URL like:

json
1{
2  "mcpServers": {
3    "keywords-ai": {
4      "url": "https://your-project.vercel.app/mcp"
5    }
6  }
7}

This is explicitly called out as “ideal for teams” because you deploy once and avoid exposing client-side keys.

---

Cursor MCP Setup

Your docs point to Cursor’s MCP config at:

• ~/.cursor/mcp.json

Cursor + Keywords AI MCP (Public HTTP)

Put the hosted config in ~/.cursor/mcp.json (from your docs), restart Cursor.

Cursor + Keywords AI MCP (Local stdio)

Cursor config switches to a command-based server:

json
1{
2  "mcpServers": {
3    "keywords-ai": {
4      "command": "node",
5      "args": ["/Users/yourname/keywordsai-mcp/dist/lib/index.js"],
6      "env": {
7        "KEYWORDS_API_KEY": "your_keywords_ai_api_key"
8      }
9    }
10  }
11}

Again: directly from your docs.

Cursor transport note (why you might see “stdio vs sse”)

Some Cursor MCP server directories describe server “type” choices like stdio or sse depending on the server endpoint offered. For Keywords AI, you’re giving people a cleaner story: streamable HTTP URL or stdio local process.

---

Claude Code MCP Setup

Claude Code’s MCP page is unusually useful because it explains:

• multiple transports (HTTP / SSE / stdio)
• how to manage scopes
• and a killer feature: Claude Code can itself run as an MCP server.

Connect Claude Code to the Keywords AI hosted MCP server (HTTP)

Claude Code recommends remote HTTP servers for cloud-based services. So Keywords AI’s hosted MCP server fits perfectly:

• URL: https://mcp.keywordsai.co/api/mcp
• Auth: Authorization: Bearer ... header

Claude Code supports adding HTTP servers via CLI with claude mcp add --transport http ... syntax.

About SSE in Claude Code

Claude Code still shows an SSE option, but marks it deprecated. If someone asks “should I use SSE?” your blog should say: no, use HTTP where available.

Local stdio in Claude Code

Claude Code supports local stdio servers (great for the local keywordsai-mcp repo setup). This maps to your “Local Stdio” mode exactly.

“Serve Claude Code as MCP” (why your readers care)

Claude Code can be started as a stdio MCP server using:

• claude mcp serve

This matters for your audience because it hints at a powerful pattern:

You can wire assistants together via MCP (Claude Code tools exposed to another client), and then use Keywords AI MCP tools inside that same workflow.

That’s how you get “workflow-y” setups without rebuilding everything.

---

MCP Tools: Logs, Traces, Prompts & Customers

Your docs list “Available tools” once connected. This is the part you should lean on as differentiation:

Logs

• list_logs: list/filter logs with queries
• get_log_detail: fetch a log by ID

Traces

• list_traces: list/filter traces
• get_trace_tree: fetch the span tree

Customers

• list_customers, get_customer_detail (including budget usage)

Prompts

• list prompts, prompt details, versions, version detail

This is the difference between “MCP is a protocol” and “MCP is useful.” Your MCP server basically turns Keywords AI into a queryable tool layer inside the assistant.

---

Debugging Workflows with MCP

Here are use cases that feel “native” to your MCP page (and not generic MCP filler):

Use case: “Why is prod suddenly expensive?”

In Cursor / Claude Code:

• “Show me the most expensive requests from the last hour.”
• Then: “Group them by customer and show budget usage for the top 3 customers.”
• Then: “Open the trace tree for the most expensive one and find which span caused the latency.”

That’s an observability workflow, but executed through MCP.

Use case: “This endpoint feels slow, prove it”

• “List logs where latency > 5 seconds.”
• “Find which prompts and prompt versions are involved.”
• “Show trace trees for the top 5 and compare where time is spent.”

Use case: “Prompt regression debugging”

• “Get the latest version of my customer-support prompt.”
• “Show me different versions of prompt xyz.”
• “Pull logs for the last deploy window and correlate failures with version changes.”

This is exactly the “different direction” you want: MCP as an interface for debugging and iteration.

---

MCP Observability & Tracing

You said: “I don’t know how to do this yet but you can think of some ways.” So here are realistic implementation patterns that are consistent with how MCP systems are structured.

Pattern A: Observe at the MCP server boundary (recommended)

If you control the MCP server (your open-source keywordsai-mcp or a fork), you can wrap every tool handler:

• record: tool name, arguments (redact sensitive), duration, success/error

• emit as:

  • a Keywords AI log event (one per tool call), and/or
  • a Keywords AI trace span (one span per tool call)

This gets you:

• “Which MCP tools are being used?”
• “Which queries are slow / error-prone?”
• “What’s the p95 for get_trace_tree?”

Why this is clean: it doesn’t require hacking Cursor/Claude clients. It’s purely server-side.

Pattern B: Correlate MCP calls with the originating LLM request

The hard part isn’t logging MCP calls. It’s tying them to the “parent” LLM request.

Two practical correlation strategies:

1. Session correlation

   • Generate a session_id in the client-side workflow (or project scope)
   • Pass it through MCP tool arguments or metadata
   • Use it as a join key in Keywords AI (logs/traces/customers)

2. Traceparent-style propagation

   • If your workflow already uses tracing, propagate trace context into MCP calls (headers in HTTP mode, env/args in stdio mode)
   • Each MCP tool call becomes a child span in the overall trace

This is how you turn “MCP happened” into “MCP happened because the model decided X.”

Pattern C: “Observe the observer” (MCP server usage analytics)

Because the Keywords AI MCP server provides access to:

• logs, traces, customers, prompts …you can also build meta dashboards like:

• Most common MCP queries inside Cursor (what engineers ask)

• Most used observability dimensions (latency vs cost vs error rate)

• Top MCP tools by usage and time

This becomes a feedback loop on your users’ debugging behavior.

Pattern D: Use Private HTTP mode as the “team observability choke point”

Your “Private HTTP (Teams)” mode (Vercel deployment) is perfect for this.

Because everyone goes through one shared URL, you can:

• standardize instrumentation
• add rate limiting / caching
• add redaction rules
• add org-level usage metrics
• implement allowlists (“which tools can Cursor call?”)

It’s not just “avoid client-side API keys.” It’s also “centralize behavior and auditing.”

---

MCP Architecture by Team Size

Solo dev / fastest path

• Public HTTP to https://mcp.keywordsai.co/api/mcp
• Use the MCP tools mainly for interactive debugging (“show expensive logs”, “open trace tree”, etc.)

Power user / customization

• Local stdio build of keywordsai-mcp
• Add lightweight instrumentation around tool handlers (Pattern A)

Team / production

• Private HTTP deployed once to Vercel (docs’ recommended team pattern)
• Add correlation + instrumentation (Patterns A + B + D)

Enterprise

• Use your docs’ enterprise override headers/env vars to target custom API endpoints.
• Add policy controls around which tools are exposed and how outputs are redacted.

---

MCP Troubleshooting Guide

Your docs already list the most common issues:

• MCP server not showing: config path, JSON syntax, restart tool fully, build step for stdio
• Auth errors: header must be Authorization: Bearer ..., env var correctness
• Timeouts: internet, base URL, Vercel deployment active

Add one Claude Code–specific footnote that saves people hours:

• Claude Code warns about tool output token limits and has env vars like MAX_MCP_OUTPUT_TOKENS.