# Connect an MCP client

Your agent reaches an MCP server through Catalyst's MCP proxy endpoint instead of connecting to the upstream server directly. This page shows how to point a standard MCP client at that endpoint, authenticate, and discover tools. No Catalyst SDK is required — any MCP client that speaks Streamable HTTP works.

## Prerequisites

- An [`MCPServer`](https://docs.diagrid.io/operate/project-operations/mcp-servers) connection in your project. If you don't have one, [add an MCP server](https://docs.diagrid.io/develop/mcp/mcpserver-getting-started) first.
- The ID your agent runs as, and its API token.
- The caller agent [granted access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) to the server's tools — a new MCP server denies everything until you grant access.

## The endpoint

Catalyst exposes each MCP server on your project's HTTP endpoint at a path keyed by the connection name:

```
<DAPR_HTTP_ENDPOINT>/v1.0/diagrid/mcp/<mcp-server-name>
```

- **`DAPR_HTTP_ENDPOINT`** is your project's HTTP endpoint. `diagrid dev run` injects it into your app as an environment variable; for a hosted project it is the HTTP endpoint shown in the [Catalyst console](https://catalyst.diagrid.io) (for example `https://http-prj<project-id>.api.r1.diagrid.io`). During local development it is `http://localhost:3500`.
- **`<mcp-server-name>`** is the name of the `MCPServer` connection — not the upstream URL, which Catalyst keeps hidden.

Authenticate every request with your API token in the **`dapr-api-token`** header. Catalyst injects the upstream server's own credentials separately, so the agent never holds them.

:::note
If your MCP server terminates TLS with a private or self-signed certificate, the region operator must add its CA to the sidecar trust — otherwise Catalyst rejects the upstream connection with a certificate-verification error. See [Sidecar Outbound TLS Trust](https://docs.diagrid.io/operate/hosting/enterprise-self-hosted/reference#sidecar-outbound-tls-trust) in the Helm chart reference.
:::

## Connect and discover tools

Point your MCP client at the Catalyst endpoint and set the token header. The example uses the Python `mcp` library with the Streamable HTTP transport:

```python
import os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

DAPR_HTTP_ENDPOINT = os.getenv("DAPR_HTTP_ENDPOINT", "http://localhost:3500")
DAPR_API_TOKEN = os.getenv("DAPR_API_TOKEN", "")
MCP_URL = f"{DAPR_HTTP_ENDPOINT}/v1.0/diagrid/mcp/mcp-server"

headers = {"dapr-api-token": DAPR_API_TOKEN}

async with streamablehttp_client(url=MCP_URL, headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()        # only the tools you're granted
        result = await session.call_tool("add", {"a": 2, "b": 3})
```

MCP clients are available in Python, TypeScript, Java, C#, and Go. Set the same URL and `dapr-api-token` header in whichever client your agent framework uses.

`session.list_tools()` returns only the tools the calling agent is allowed to use — Catalyst filters discovery, so unauthorized tools are invisible rather than merely un-callable. A `call_tool` for a tool you're not granted is rejected with `403 Forbidden` before it reaches the upstream server.

## Discover available servers

To list the MCP servers the calling agent may reach, send a `GET` to the discovery path:

```bash
curl -s "$DAPR_HTTP_ENDPOINT/v1.0/diagrid/mcp" \
  -H "dapr-api-token: $DAPR_API_TOKEN"
```

The response is a JSON array of the servers in scope for this caller, each with the path to connect on:

```json
[
  { "name": "mcp-server", "connect": { "path": "/v1.0/diagrid/mcp/mcp-server" } }
]
```

The list contains only servers the caller is authorized for, so it stays empty until access is granted.

## What's next

- [Control tool access](https://docs.diagrid.io/develop/mcp/mcp-access-policies) — grant the caller access to specific tools.
- [Add an MCP server](https://docs.diagrid.io/develop/mcp/mcpserver-getting-started) — enable more servers from the catalog or your own URL.
- [Authentication](https://docs.diagrid.io/develop/mcp/mcp-authentication) — how the client authenticates to Catalyst and Catalyst to the upstream server.