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

# MCP Client

> Connect external MCP servers (tools) to your Guru to enhance answers

## Introduction

MCP Client Connections let you connect external [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers to your Guru. When a user asks a question, your Guru can call tools from these connected servers to fetch real-time data, perform lookups, or execute actions as part of generating its answer.

For example, you could connect:

* A database MCP server so your Guru can query live data
* An internal API server so your Guru can fetch user-specific information
* A monitoring MCP server so your Guru can check system status

<Note>
  This is different from the [MCP Server](/guides/mcp-server) feature, which
  exposes your Guru **as** an MCP server. MCP Client Connections let your Guru
  **consume** external MCP servers.
</Note>

## Prerequisites

* A Guru on [Gurubase Cloud](https://app.gurubase.io) or a self-hosted instance
* An external MCP server you want to connect (remote HTTP endpoint, or a local command for self-hosted only)
* API enabled on your Guru (Settings > Integrations > API)

## Adding a Connection

1. Navigate to your Guru's settings
2. Click **MCP** in the sidebar
3. Select the **MCP Clients** tab
4. Click **Add Connection**
5. Fill in the connection details:
   * **Name**: A descriptive name for the connection
   * **Server Config (JSON)**: The MCP server configuration (see [Configuration Format](#configuration-format) below)
   * **Tool Cache TTL**: How long discovered tools are cached (default: 600 seconds)
   * **Tool Timeout**: Max time for tool discovery and execution (default: 10 seconds)
6. Click **Test Connection** to verify it works
7. Click **Create** to save

## Configuration Format

The server config is a JSON object. The format depends on whether your MCP server is a local command (stdio) or a remote HTTP endpoint.

### Local Server (stdio)

<Note type="warning">
  Local (stdio) connections are only available in **self-hosted** deployments.
  On Gurubase Cloud, use a [Remote Server (Streamable HTTP)](#remote-server-streamable-http) instead.
</Note>

Use this when the MCP server runs as a subprocess on the backend. The config must contain a `command` field.

```json theme={null}
{
  "command": "npx",
  "args": ["-y", "your-mcp-server"],
  "env": {
    "API_KEY": "your-api-key"
  }
}
```

| Field     | Type   | Required | Description                              |
| --------- | ------ | -------- | ---------------------------------------- |
| `command` | string | Yes      | The command to run                       |
| `args`    | array  | No       | Command arguments                        |
| `env`     | object | No       | Environment variables for the subprocess |

### Remote Server (Streamable HTTP)

Use this when the MCP server is accessible over HTTP. The config must contain a `url` field.

```json theme={null}
{
  "url": "https://your-mcp-server.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}
```

| Field     | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `url`     | string | Yes      | The MCP server URL                      |
| `headers` | object | No       | HTTP headers (e.g., for authentication) |

<Note type="warning">
  The config must contain either `command` (for stdio, self-hosted only) or `url` (for HTTP).
  If neither is present, the connection will be invalid.
</Note>

## Testing Connections

Before saving, use the **Test Connection** button to verify your configuration:

* **Success**: Shows the number of tools discovered from the server (e.g., "Connection successful: 3 tools found")
* **Failure**: Shows an error message indicating what went wrong (e.g., timeout, invalid URL, authentication error)

Testing uses the **Tool Timeout** value you configured. If the server takes longer than the timeout to respond, the test will fail.

## Managing Connections

### Enable / Disable

Toggle a connection on or off from the actions menu (three-dot icon) on each row. Disabled connections are skipped during question answering.

### Edit

Click **Edit** in the actions menu to modify the connection name, config, cache TTL, or timeout.

### Delete

Click **Delete** in the actions menu. A confirmation dialog will appear before the connection is removed.

### View Discovered Tools

Click **View Tools** in the actions menu to see all tools discovered from the MCP server. For each tool you can see:

* Tool name and description
* Parameters (name, type, required, description)
* A **Test** button to execute the tool with custom arguments and see the result

## How It Works

When a user asks a question to your Guru:

1. **Tool Discovery**: Gurubase discovers available tools from each enabled MCP connection (results are cached based on the Tool Cache TTL)
2. **Tool Selection**: During answer generation, the AI evaluates which MCP tools (if any) are relevant to the question
3. **Tool Execution**: If a tool is selected, Gurubase calls it on the external MCP server with the appropriate arguments
4. **Answer Generation**: The tool's response is incorporated into the Guru's answer as additional context

Tools from MCP connections appear alongside any [custom actions](/guides/actions) you've configured. The per-guru tool limit applies to the combined total of MCP tools across all connections.

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Server" icon="server" href="/guides/mcp-server">
    Expose your Guru as an MCP server
  </Card>

  <Card title="Actions" icon="bolt" href="/guides/actions">
    Create custom API call actions for your Guru
  </Card>
</CardGroup>