> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keywordsai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Tabs>
  <Tab title="Public HTTP (Recommended)">
    Connect to Keywords AI's hosted MCP server. The simplest setup - no installation required.

    <Steps>
      <Step title="Get your API key">
        Get your Keywords AI API key from [platform.keywordsai.co](https://platform.keywordsai.co/platform/api/api-keys).
      </Step>

      <Step title="Configure your AI tool">
        Add to your MCP configuration file:

        <CodeGroup>
          ```json Cursor (~/.cursor/mcp.json) theme={"system"}
          {
            "mcpServers": {
              "keywords-ai": {
                "url": "https://mcp.keywordsai.co/api/mcp",
                "headers": {
                  "Authorization": "Bearer your_keywords_ai_api_key"
                }
              }
            }
          }
          ```

          ```json Claude Desktop (macOS) theme={"system"}
          // ~/Library/Application Support/Claude/claude_desktop_config.json
          {
            "mcpServers": {
              "keywords-ai": {
                "url": "https://mcp.keywordsai.co/api/mcp",
                "headers": {
                  "Authorization": "Bearer your_keywords_ai_api_key"
                }
              }
            }
          }
          ```

          ```json Claude Desktop (Windows) theme={"system"}
          // %APPDATA%\Claude\claude_desktop_config.json
          {
            "mcpServers": {
              "keywords-ai": {
                "url": "https://mcp.keywordsai.co/api/mcp",
                "headers": {
                  "Authorization": "Bearer your_keywords_ai_api_key"
                }
              }
            }
          }
          ```
        </CodeGroup>
      </Step>

      <Step title="Restart your AI tool">
        Restart Cursor or Claude Desktop to load the MCP server.
      </Step>
    </Steps>

    <Tip>
      This is the recommended setup for most users. No installation, no maintenance - just configure and go.
    </Tip>
  </Tab>

  <Tab title="Local Stdio">
    Run the MCP server locally via stdio - for personal development or offline use.

    <Steps>
      <Step title="Prerequisites">
        * [Node.js](https://nodejs.org/) v18 or higher
        * [Git](https://git-scm.com/)
      </Step>

      <Step title="Clone and build the project">
        ```bash theme={"system"}
        git clone https://github.com/Keywords-AI/keywordsai-mcp.git
        cd keywordsai-mcp
        npm install
        npm run build
        ```
      </Step>

      <Step title="Get your API key">
        Get your Keywords AI API key from [platform.keywordsai.co](https://platform.keywordsai.co/platform/api/api-keys).
      </Step>

      <Step title="Configure your AI tool">
        Add to your MCP configuration file. **Important:** Replace the path with your actual installation path.

        <CodeGroup>
          ```json Cursor (~/.cursor/mcp.json) theme={"system"}
          {
            "mcpServers": {
              "keywords-ai": {
                "command": "node",
                "args": ["/Users/yourname/keywordsai-mcp/dist/lib/index.js"],
                "env": {
                  "KEYWORDS_API_KEY": "your_keywords_ai_api_key"
                }
              }
            }
          }
          ```

          ```json Claude Desktop (macOS) theme={"system"}
          // ~/Library/Application Support/Claude/claude_desktop_config.json
          {
            "mcpServers": {
              "keywords-ai": {
                "command": "node",
                "args": ["/Users/yourname/keywordsai-mcp/dist/lib/index.js"],
                "env": {
                  "KEYWORDS_API_KEY": "your_keywords_ai_api_key"
                }
              }
            }
          }
          ```

          ```json Claude Desktop (Windows) theme={"system"}
          // %APPDATA%\Claude\claude_desktop_config.json
          {
            "mcpServers": {
              "keywords-ai": {
                "command": "node",
                "args": ["C:/Users/yourname/keywordsai-mcp/dist/lib/index.js"],
                "env": {
                  "KEYWORDS_API_KEY": "your_keywords_ai_api_key"
                }
              }
            }
          }
          ```
        </CodeGroup>
      </Step>

      <Step title="Restart your AI tool">
        Restart Cursor or Claude Desktop to load the MCP server.
      </Step>
    </Steps>

    <Note>
      After updating the code, run `npm run build` again and restart your AI tool.
    </Note>
  </Tab>

  <Tab title="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.

    <Steps>
      <Step title="Deploy to Vercel">
        Click to deploy with one click:

        [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/Keywords-AI/keywordsai-mcp\&env=KEYWORDS_API_KEY\&envDescription=Your%20Keywords%20AI%20API%20key\&envLink=https://platform.keywordsai.co/platform/api/api-keys)

        Or deploy manually:

        ```bash theme={"system"}
        git clone https://github.com/Keywords-AI/keywordsai-mcp.git
        cd keywordsai-mcp
        vercel deploy --prod
        ```
      </Step>

      <Step title="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
      </Step>

      <Step title="Configure your AI tool">
        Share this config with your team (replace with your Vercel URL):

        ```json theme={"system"}
        {
          "mcpServers": {
            "keywords-ai": {
              "url": "https://your-project.vercel.app/mcp"
            }
          }
        }
        ```
      </Step>
    </Steps>

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

***

## 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](https://platform.keywordsai.co/platform/api/api-keys).

***

## Enterprise configuration

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

<Tabs>
  <Tab title="HTTP Mode">
    Add the `keywords-api-base-url` header:

    ```json theme={"system"}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Stdio Mode">
    Add the `KEYWORDS_API_BASE_URL` environment variable:

    ```json theme={"system"}
    {
      "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"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

**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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

***

## Source code

The Keywords AI MCP server is open source:

<Card title="GitHub Repository" icon="github" href="https://github.com/Keywords-AI/keywordsai-mcp">
  View source code, report issues, and contribute
</Card>