Model Context Protocol (MCP)

Access Keywords AI data directly from your AI coding assistant using MCP

The Model Context Protocol (MCP) is a standardized framework that enables AI models to interact with external data sources and tools. It allows for real-time access to your Keywords AI logs, traces, prompts, and customer data directly from your coding environment.

Getting started

Keywords AI provides an MCP server that gives your AI tools direct access to your observability data. The server supports both HTTP streamable (for hosted deployments) and stdio (for local use).

Installation

Public HTTP (Recommended)

Connect to Keywords AI’s hosted MCP server. The simplest setup - no installation required.

1. Get your API key

   Get your Keywords AI API key from platform.keywordsai.co.

2. Configure your AI tool

   Add to your MCP configuration file:

   Cursor (~/.cursor/mcp.json)

   {
     "mcpServers": {
       "keywords-ai": {
         "url": "https://mcp.keywordsai.co/api/mcp",
         "headers": {
           "Authorization": "Bearer your_keywords_ai_api_key"
         }
       }
     }
   }
   
3. Restart your AI tool

   Restart Cursor or Claude Desktop to load the MCP server.

This is the recommended setup for most users. No installation, no maintenance - just configure and go.

Local Stdio

Run the MCP server locally via stdio - for personal development or offline use.

1. Prerequisites

   • Node.js v18 or higher
   • Git
2. Clone and build the project

   git clone https://github.com/Keywords-AI/keywordsai-mcp.git
   cd keywordsai-mcp
   npm install
   npm run build
   
3. Get your API key

   Get your Keywords AI API key from platform.keywordsai.co.

4. Configure your AI tool

   Add to your MCP configuration file. Important: Replace the path with your actual installation path.

   Cursor (~/.cursor/mcp.json)

   {
     "mcpServers": {
       "keywords-ai": {
         "command": "node",
         "args": ["/Users/yourname/keywordsai-mcp/dist/lib/index.js"],
         "env": {
           "KEYWORDS_API_KEY": "your_keywords_ai_api_key"
         }
       }
     }
   }
   
5. Restart your AI tool

   Restart Cursor or Claude Desktop to load the MCP server.

After updating the code, run npm run build again and restart your AI tool.

Private HTTP (Teams)

Deploy your own instance to Vercel with your API key stored as an environment variable. Perfect for teams - no client-side keys needed.

1. Deploy to Vercel

   Click to deploy with one click:

   

   Or deploy manually:

   git clone https://github.com/Keywords-AI/keywordsai-mcp.git
   cd keywordsai-mcp
   vercel deploy --prod
   
2. Set environment variable

   In Vercel Dashboard → Your Project → Settings → Environment Variables:

   • Add KEYWORDS_API_KEY = your_keywords_ai_api_key
   • Redeploy for changes to take effect
3. Configure your AI tool

   Share this config with your team (replace with your Vercel URL):

   {
     "mcpServers": {
       "keywords-ai": {
         "url": "https://your-project.vercel.app/mcp"
       }
     }
   }
   

This mode is ideal for teams - deploy once, and everyone can use the same URL without exposing API keys in their local config.

---

Authentication

Mode	API Key Location	Best For
Public HTTP	Authorization header	Individual users, quick setup
Local Stdio	KEYWORDS_API_KEY env var	Personal development, offline use
Private HTTP	Vercel environment variable	Teams, shared access

Get your Keywords AI API key from platform.keywordsai.co.

---

Enterprise configuration

For enterprise users with a custom API endpoint (e.g., endpoint.keywordsai.co), you can override the default API base URL.

HTTP Mode

Add the keywords-api-base-url header:

{
  "mcpServers": {
    "keywords-ai": {
      "url": "https://mcp.keywordsai.co/api/mcp",
      "headers": {
        "Authorization": "Bearer your_keywords_ai_api_key",
        "keywords-api-base-url": "https://endpoint.keywordsai.co/api"
      }
    }
  }
}

Stdio Mode

Add the KEYWORDS_API_BASE_URL environment variable:

{
  "mcpServers": {
    "keywords-ai": {
      "command": "node",
      "args": ["/path/to/keywordsai-mcp/dist/lib/index.js"],
      "env": {
        "KEYWORDS_API_KEY": "your_keywords_ai_api_key",
        "KEYWORDS_API_BASE_URL": "https://endpoint.keywordsai.co/api"
      }
    }
  }
}

Supported endpoints:

Endpoint	URL
Default (Cloud)	https://api.keywordsai.co/api
Enterprise	https://endpoint.keywordsai.co/api
Local development	http://localhost:8000/api

---

Available tools

Once connected, your AI tools have access to the following Keywords AI features.

Logs

Tool	Description
list_logs	List and filter LLM request logs with powerful query capabilities
get_log_detail	Retrieve complete details of a single log by unique ID

Example queries:

• “Show me the most expensive requests from the last hour”
• “Find all failed requests for customer user_123”
• “List logs where latency > 5 seconds”

Traces

Tool	Description
list_traces	List and filter traces with sorting and pagination
get_trace_tree	Retrieve complete hierarchical span tree of a trace

Example queries:

• “Show me traces with errors in production”
• “Get the span tree for trace xyz123”
• “Find traces that cost more than $0.10”

Customers

Tool	Description
list_customers	List customers with pagination and sorting
get_customer_detail	Get customer details including budget usage

Example queries:

• “Who are my top 10 customers by cost?”
• “Show customer budget usage for user_abc”
• “List customers sorted by number of requests”

Prompts

Tool	Description
list_prompts	List all prompts in your organization
get_prompt_detail	Get detailed prompt information
list_prompt_versions	List all versions of a prompt
get_prompt_version_detail	Get specific version details

Example queries:

• “Show me all my prompts”
• “Get the latest version of my customer-support prompt”
• “What are the different versions of prompt xyz?”

---

Troubleshooting

MCP server not showing in Cursor/Claude Desktop

1. Verify your config file path is correct
2. Check JSON syntax (use a JSON validator)
3. Restart your AI tool completely (not just reload)
4. For stdio mode: ensure npm run build completed successfully

Authentication errors

1. Verify your API key is correct
2. For HTTP mode: ensure header is Authorization: Bearer YOUR_KEY (not just the key)
3. For stdio mode: check the KEYWORDS_API_KEY env var is set correctly

Connection timeout or errors

1. Check your internet connection
2. For enterprise: verify KEYWORDS_API_BASE_URL is correct
3. For private HTTP: ensure Vercel deployment is active

---

Source code

The Keywords AI MCP server is open source:

GitHub Repository

View source code, report issues, and contribute