# MCP Servers

MCP (Model Context Protocol) servers provide a standardized way to connect agents to external tools and data sources. MCP is an open protocol that enables secure, two-way connections between AI systems and external services.

{% hint style="info" %}
**Looking to query Alhena from Claude?** This page covers connecting Alhena's AI agents to *external* MCP servers. If you want to use Claude (claude.ai or Claude Code) to query your own Alhena conversations and analytics, see [Claude Integration (MCP)](/docs/features/claude-mcp.md) instead.
{% endhint %}

**Plan required:** Pro

## Why Use MCP?

MCP offers advantages over simple API tools:

* **Multiple tools per server** - One connection can expose many capabilities
* **Standardized protocol** - Works with any MCP-compatible server
* **Rich tool definitions** - Servers can describe their tools with detailed schemas
* **Two-way communication** - Supports more complex interaction patterns

## Use Cases

* Connect to databases for real-time queries
* Integrate with complex enterprise systems
* Use pre-built MCP connectors for common services
* Build custom integrations with full programmatic control
* Access multiple related tools through a single connection

{% hint style="success" %}
**Zapier Integration**

Zapier offers MCP server support, giving you access to thousands of integrations without writing code. You can create custom MCP servers in Zapier to connect your agents to services like Google Sheets, Salesforce, Slack, and more. Visit [Zapier's MCP documentation](https://zapier.com/mcp) to get started.
{% endhint %}

## Adding an MCP Server

Navigate to **Integrations > Custom Extensions > MCP Integrations** and click **Add new MCP server**.

### Step 1: Server Configuration

| Field            | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| **Server name**  | A descriptive name for this server connection                 |
| **Description**  | Optional description of what this server provides             |
| **Endpoint URL** | The MCP server endpoint (e.g., `https://mcp.example.com/api`) |
| **Headers**      | Optional authentication headers (API keys, tokens)            |

Click **Add Header** to add authentication. Use the visibility toggle to hide sensitive values.

**Common header patterns:**

```
Authorization: Bearer your-token
X-API-Key: your-api-key
```

### Step 2: Test Connection

Click **Test Connection** to verify:

* The endpoint is reachable
* Authentication credentials are valid
* The server responds with the MCP protocol

If the test fails, check your endpoint URL and credentials.

### Step 3: Select Tools and Assign Agents

After a successful connection, the server returns its available tools. You'll see a table with:

* **Status** - Toggle to enable/disable each tool
* **Tool Name** - The tool identifier
* **Description** - What the tool does
* **Assigned Agent** - Which agent can use this tool

For each tool you want to use:

1. Toggle the status to enable it
2. Select which agent should have access to this tool

### Step 4: Finish Setup

Click **Finish Setup** to save the MCP server configuration.

## Managing MCP Servers

### View registered servers

All registered MCP servers appear in **Integrations > Custom Extensions > MCP Integrations**. Click a server to view and edit its configuration.

### Enable or disable tools

On the server edit page, use the toggle switch next to each tool to enable or disable it. Disabled tools won't be available to agents.

### Reassign tools to different agents

Click **Assign** next to a tool to change which agent has access to it.

### Refresh tools

If the MCP server adds new tools, click **Refresh Tools** to fetch the updated list. New tools will appear in the table and can be assigned to agents.

### Update server settings

To modify a registered server:

1. Click the server entry
2. Click **Configure settings** to expand
3. Update the name or description
4. Click **Save Changes**

{% hint style="info" %}
Connection settings (endpoint URL and headers) cannot be changed after creation. To use different connection settings, delete the server and create a new one.
{% endhint %}

### Delete a server

To remove an MCP server:

1. Click the server entry
2. Click **Configure settings** to expand
3. Click **Delete Server**
4. Confirm the deletion

{% hint style="warning" %}
Deleting a server immediately disables all its tools for all agents using them.
{% endhint %}

## Building Custom MCP Servers

You can build your own MCP servers to expose custom functionality.

* [MCP Protocol Specification](https://modelcontextprotocol.io/)
* [MCP Server Examples](https://github.com/modelcontextprotocol/servers)

## Best Practices

### Choose specific tool names

Tools with clear, specific names help the agent understand when to use them. "get\_order\_status" is better than "query".

### Write detailed tool descriptions

The MCP protocol allows rich tool descriptions. Use them to explain:

* What the tool does
* When to use it
* What parameters are required
* What the response contains

### Limit enabled tools

Only enable tools that your agents actually need. Too many tools can confuse the agent about which to use.

### Monitor tool usage

Review conversation logs to see how agents are using your MCP tools. Look for:

* Tools that never get called (unclear descriptions?)
* Tools called in wrong situations (description too broad?)
* Errors or unexpected responses

### Handle errors gracefully

Your MCP server should return helpful error messages that the agent can communicate to users. Avoid technical error codes without explanation.

## Troubleshooting

| Issue                 | Solution                                                  |
| --------------------- | --------------------------------------------------------- |
| Connection test fails | Verify the endpoint URL is correct and accessible         |
| Authentication fails  | Check that headers are correct and credentials are valid  |
| No tools appear       | Verify the server implements MCP tool discovery correctly |
| Tool calls fail       | Check server logs for errors                              |
| Agent uses wrong tool | Review tool descriptions for clarity                      |

## Related

* [API Tools](/docs/integrations/custom-extensions/api-tools.md) - For simpler HTTP integrations
* [Sheet Search](/docs/integrations/custom-extensions/sheet-search.md) - For spreadsheet data access
* [Custom Agents](/docs/ai-configuration/agents/custom-agents.md) - Assign tools to specific agents


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alhena.gitbook.io/docs/integrations/custom-extensions/mcp-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.