Model Context Protocol (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)
Local Stdio
Private HTTP (Teams)

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

Get your API key

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

Configure your AI tool

Add to your MCP configuration file:

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

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.

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

Prerequisites

Node.js v18 or higher
Git

Clone and build the project

git clone https://github.com/Keywords-AI/keywordsai-mcp.git
cd keywordsai-mcp
npm install
npm run build

Get your API key

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

Configure your AI tool

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

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

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.

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

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

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

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
Stdio 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"
      }
    }
  }
}

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

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

Authentication errors

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

Connection timeout or errors

Check your internet connection
For enterprise: verify KEYWORDS_API_BASE_URL is correct
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

Get started

Features

Admin

Security

Resources

Help & Community

Model Context Protocol (MCP)

Getting started

Installation

Authentication

Enterprise configuration

Available tools

Logs

Traces

Customers

Prompts

Troubleshooting

Source code

GitHub Repository

Get started

Features

Admin

Security

Resources

Help & Community

​Getting started

​Installation

​Authentication

​Enterprise configuration

​Available tools

​Logs

​Traces

​Customers

​Prompts

​Troubleshooting

​Source code

GitHub Repository

Getting started

Installation

Authentication

Enterprise configuration

Available tools

Logs

Traces

Customers

Prompts

Troubleshooting

Source code