Skip to main content

​
Introduction

MCP Client Connections let you connect external MCP (Model Context Protocol) 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
This is different from the MCP Server feature, which exposes your Guru as an MCP server. MCP Client Connections let your Guru consume external MCP servers.

​
Prerequisites

  • A Guru on Gurubase Cloud 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 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)

Local (stdio) connections are only available in self-hosted deployments. On Gurubase Cloud, use a Remote Server (Streamable HTTP) instead.
Use this when the MCP server runs as a subprocess on the backend. The config must contain a command field. 
{
  "command": "npx",
  "args": ["-y", "your-mcp-server"],
  "env": {
    "API_KEY": "your-api-key"
  }
}
FieldTypeRequiredDescription
commandstringYesThe command to run
argsarrayNoCommand arguments
envobjectNoEnvironment 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. 
{
  "url": "https://your-mcp-server.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}
FieldTypeRequiredDescription
urlstringYesThe MCP server URL
headersobjectNoHTTP headers (e.g., for authentication)
The config must contain either command (for stdio, self-hosted only) or url (for HTTP). If neither is present, the connection will be invalid.

​
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 you’ve configured. The per-guru tool limit applies to the combined total of MCP tools across all connections.

​
Next Steps

MCP Server

Expose your Guru as an MCP server

Actions

Create custom API call actions for your Guru