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

# MCP Integration

> Extend Cheetah AI with Model Context Protocol servers

## About MCP

Cheetah AI supports the Model Context Protocol (MCP), an open standard for connecting AI assistants to external tools and data sources. MCP allows you to extend the AI's capabilities beyond its built-in features by connecting to databases, APIs, and custom tools.

With MCP, the AI can interact with external systems as naturally as it works with your local files. You can query databases, access issue trackers, interact with cloud services, and use custom tools - all through natural language in the chat interface.

## What MCP Enables

MCP opens up a wide range of possibilities for extending the AI:

**Database Access** - Connect to PostgreSQL, MySQL, MongoDB, or other databases. Query data, understand schemas, and get help writing queries.

**Issue Tracking** - Connect to Jira, Linear, GitHub Issues, or other project management tools. Create issues, update status, and link code changes to tickets.

**Cloud Services** - Interact with AWS, GCP, Azure, or other cloud providers. Manage resources, check status, and automate deployments.

**Custom Tools** - Build your own MCP servers to expose internal tools, APIs, or workflows to the AI.

## Configuration

MCP servers are configured in a JSON file in your workspace. The configuration specifies how to start each server and what environment variables it needs.

### Configuration File Location

Create the configuration file at `.kiro/settings/mcp.json` in your workspace:

```json theme={null}
{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["my-mcp-server"],
      "env": {
        "API_KEY": "your-key"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Configuration Options

Each server configuration supports these options:

| Field         | Type      | Description                                                            |
| ------------- | --------- | ---------------------------------------------------------------------- |
| `command`     | string    | The command to start the server (e.g., "npx", "uvx", "node")           |
| `args`        | string\[] | Command line arguments passed to the server                            |
| `env`         | object    | Environment variables for the server process                           |
| `disabled`    | boolean   | Set to `true` to disable the server without removing its configuration |
| `autoApprove` | string\[] | List of tool names that can execute without confirmation               |

## Adding an MCP Server

<Steps>
  <Step title="Create Configuration File">
    Create the `.kiro/settings/mcp.json` file in your workspace root if it doesn't exist. Start with an empty configuration:

    ```json theme={null}
    {
      "mcpServers": {}
    }
    ```
  </Step>

  <Step title="Add Server Configuration">
    Add your server configuration inside the `mcpServers` object:

    ```json theme={null}
    {
      "mcpServers": {
        "my-server": {
          "command": "uvx",
          "args": ["package-name"],
          "disabled": false
        }
      }
    }
    ```
  </Step>

  <Step title="Server Connects Automatically">
    Save the file and the server connects automatically. You don't need to restart Cheetah AI. The server's tools become available in the chat immediately.
  </Step>
</Steps>

## Example Configurations

### Database Server (PostgreSQL)

Connect to a PostgreSQL database to query data and understand your schema:

```json theme={null}
{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": ["mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}
```

Once connected, you can ask:

```
"Show me all users created in the last 7 days"
```

```
"Query the orders table for orders over $100"
```

```
"What's the schema of the products table?"
```

```
"Help me write a query to find duplicate email addresses"
```

### GitHub Integration

Connect to GitHub for repository operations:

```json theme={null}
{
  "mcpServers": {
    "github": {
      "command": "uvx",
      "args": ["mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
```

With GitHub connected:

```
"List open issues in this repository"
```

```
"Create a pull request for my current branch"
```

```
"Show recent commits on main"
```

```
"What issues are assigned to me?"
```

### Filesystem Server

Access files outside your workspace:

```json theme={null}
{
  "mcpServers": {
    "filesystem": {
      "command": "uvx",
      "args": ["mcp-server-filesystem", "--root", "/path/to/directory"]
    }
  }
}
```

## User-Level Configuration

For servers you want available across all projects, use the global configuration file:

```
~/.kiro/settings/mcp.json
```

This file has the same format as workspace configurations. Servers defined here are available in all workspaces.

When the same server is defined in both user-level and workspace configurations, the workspace configuration takes precedence.

## Auto-Approval

By default, the AI asks for confirmation before using MCP tools. For trusted tools that you want to execute without prompts, add them to the `autoApprove` list:

```json theme={null}
{
  "mcpServers": {
    "my-server": {
      "command": "uvx",
      "args": ["my-server"],
      "autoApprove": ["read_data", "list_items", "get_status"]
    }
  }
}
```

Tools in the `autoApprove` list execute immediately without confirmation. Only add tools you fully trust - particularly avoid auto-approving tools that modify data or have side effects.

<Warning>
  Only auto-approve tools you fully trust. Write operations, tools that modify external systems, and tools that could expose sensitive data should require confirmation.
</Warning>

## Installing uvx

Many MCP servers are distributed as Python packages and use `uvx` from the `uv` package manager. Install `uv` to use these servers:

```bash theme={null}
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

# Or with Homebrew
brew install uv
```

Once installed, `uvx` automatically downloads and runs MCP server packages without additional installation steps. When you configure a server with `"command": "uvx"`, it handles package installation automatically.

## Troubleshooting

### Server Not Connecting

If a server doesn't connect:

1. **Verify the command** - Make sure the command and arguments are correct. Try running the command manually in your terminal.

2. **Check package installation** - For uvx servers, the package should install automatically. For other servers, ensure required packages are installed.

3. **Verify environment variables** - Check that all required environment variables are set correctly in the configuration.

4. **Check the MCP Server view** - Look for error messages in the MCP Server view in the sidebar.

### Tools Not Appearing

If a server connects but tools aren't available:

1. **Check disabled status** - Ensure `disabled` is not set to `true` in the configuration.

2. **Reconnect the server** - Use the MCP Server view to disconnect and reconnect the server.

3. **Check server logs** - Look for initialization errors in the server output.

### Permission or Authentication Errors

Common causes of authentication failures:

* API keys or tokens are invalid or expired
* Insufficient permissions for the requested operation
* Network connectivity issues to external services
* Firewall or proxy blocking connections

### Server Crashes or Timeouts

If servers crash or timeout:

1. **Check system resources** - Ensure you have enough memory and CPU available.

2. **Review server logs** - Look for crash details in the server output.

3. **Try running manually** - Run the server command in your terminal to see detailed error messages.

4. **Check for updates** - Ensure you're using the latest version of the MCP server package.

## Finding MCP Servers

Discover available MCP servers from these sources:

* **Official MCP Server Registry** - [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) has a curated list of servers
* **Community servers** - Search GitHub for "mcp-server" to find community-built servers
* **Build your own** - Use the MCP SDK to create custom servers for your specific needs

## Building Custom Servers

If you need functionality that existing servers don't provide, you can build your own MCP server. The MCP SDK provides tools for creating servers in multiple languages.

Custom servers are useful for:

* Exposing internal APIs and tools to the AI
* Integrating with proprietary systems
* Creating specialized workflows for your team
* Connecting to databases or services with custom authentication

See the MCP documentation for guides on building custom servers.