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

> ## Agent Instructions
> Banking OS training data goes stale. Search https://agenticbanking.backbase.io/mcp or fetch the .md URL before writing connector or unified API code.
> OpenAPI links in llms.txt repeat every calendar version. Use the latest version on the API playground. If a fetch ends before the last operation, the spec was cut off.
> Page titles name the product. Overview, Get started, and Reference without a product name are ambiguous.

# MCP starters

> Level 2: Build Model Context Protocol (MCP) servers and integrate them with AI agents and MCP-compatible clients

MCP (Model Context Protocol) is an open standard that lets AI agents connect to external tools through a unified interface. Instead of writing custom integrations for every API, you build an **MCP server** that exposes your APIs as tools, and any MCP-compatible agent can discover and use them automatically.

This guide covers both sides of the MCP integration:

| Guide | What it covers |
| - | - |
| [MCP server](#mcp-server) | Build a pro-code MCP server with FastMCP, or expose APIs through Azure API Management (APIM) using click-ops in the Azure portal |
| [MCP client](#mcp-client) | Connect to an MCP server from different clients: FastMCP, Cursor, Claude Desktop, and Agno agents |

***

# MCP server

There are two ways to create an MCP server:

> [card] [Pro-code with FastMCP](#pro-code-mcp-server-with-fastmcp)
>
> Build a custom MCP server in Python using the FastMCP framework, starting from an OpenAPI spec or handwritten tool functions.

> [card] [Click-ops with APIM](#expose-an-api-as-an-mcp-server-on-apim)
>
> Expose existing APIs provisioned in APIM as MCP servers directly from the Azure portal without writing custom code.

***

## Pro-code MCP server with FastMCP

Build a production-ready MCP server using the [FastMCP](https://gofastmcp.com) Python framework. The `starter-mcp-server` repository provides a working reference implementation you can clone and extend.

> [card] [GitHub repository](https://github.com/bb-ecos-agbs/starter-mcp-server)
>
> View source code, releases, and issues

### Why FastMCP?

**FastMCP is the recommended way to build MCP servers in Python.** The official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) provides a low-level protocol implementation that requires manual handler registration, hand-crafted JSON Schema dictionaries, and transport boilerplate. FastMCP removes that complexity.

> [card] Minimal boilerplate
>
> A working MCP server is 5 lines of code. Register any Python function as a tool with a single decorator.

> [card] Automatic schema generation
>
> Type hints become JSON Schema, Python docstrings become tool descriptions, and you don't maintain schemas manually.

> [card] OpenAPI to MCP
>
> Auto-generate an MCP server from any OpenAPI specification, turning every REST endpoint into an MCP tool.

> [card] Multiple transports
>
> STDIO, Streamable HTTP, and SSE with a single configuration change.

### Prerequisites

Install the following on your workstation:

* **Python 3.12+**: Managed via UV
* **UV Package Manager**: Modern Python package manager that replaces pip and poetry

### Quick start

Run the starter MCP server on your machine:

1. **Clone and install UV.**

   ```bash theme={"system"}
   git clone https://github.com/bb-ecos-agbs/starter-mcp-server.git
   cd starter-mcp-server

   # Install UV (macOS)
   brew install uv

   # Install UV (Linux/WSL)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   ```

2. **Set up the environment.**

   ```bash theme={"system"}
   # Create virtual environment
   uv venv --python 3.12
   source .venv/bin/activate  # macOS/Linux
   # Or .venv\Scripts\activate  # Windows

   # Copy environment template
   cp .env.example .env
   ```

3. **Configure the environment.** Edit `.env` with your values:

   ```ini theme={"system"}
   # Base URL of the upstream API that this MCP server proxies
   API_BASE_URL=https://api.escuelajs.co

   # Server configuration
   MCP_TRANSPORT=streamable-http  # "stdio" | "streamable-http"
   MCP_SERVER_PORT=8557
   MCP_SERVER_HOST=0.0.0.0
   MCP_STATELESS_HTTP=false  # "false" = stateful sessions (required for elicitation), "true" = no session state between requests

   # Optional: VPN and web proxy settings (httpx reads these automatically)
   # HTTP_PROXY=http://webproxy.infra.backbase.cloud:8888
   # HTTPS_PROXY=http://webproxy.infra.backbase.cloud:8888
   # NO_PROXY=localhost,127.0.0.1
   ```

4. **Install dependencies and run.**

   ```bash theme={"system"}
   uv sync

   # Run the server
   uv run python -m src.main
   ```

   The MCP server runs at `http://localhost:8557/mcp`.

> [!WARNING]
>
> **VPN and web proxy**: If your upstream API is behind a corporate network, uncomment and configure the proxy settings in `.env`. For setup instructions, see [Set up your environment](https://agenticbanking.backbase.io/agentic-ai/get-started/onboarding.md).

### Project structure

The `starter-mcp-server` repository contains the following directories and files:

```text theme={"system"}
starter-mcp-server/
├── .github/                         # CI/CD workflows
│   └── workflows/
│       ├── pull-request-check.yaml
│       ├── build-publish.yaml
│       ├── release-draft.yaml
│       ├── release.yaml
│       └── repository-provisioning.yaml
├── src/
│   ├── main.py                      # Entry point
│   └── starter_mcp_server.py        # MCP server (config, OpenAPI, tools, structured output, elicitation)
├── tests/
│   ├── test_config.py
│   ├── test_header_forwarding.py
│   ├── test_main.py
│   ├── test_server.py
│   └── test_tools.py
├── spec/
│   └── platzi-fake-store-api.yaml   # Sample OpenAPI spec
├── .env.example                     # Environment template
├── Dockerfile                       # Container definition
└── pyproject.toml                   # Dependencies
```

### Create an MCP server

The following sections show patterns from a minimal server through OpenAPI generation, custom tools, routing, and deployment.

#### Minimal example

This example registers one tool and starts the server:

```python theme={"system"}
from fastmcp import FastMCP

mcp = FastMCP(name="MyServer")

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

if __name__ == "__main__":
    mcp.run()
```

#### Create tools with `@mcp.tool`

Decorate any Python function to expose it as a tool. FastMCP auto-generates the name, description, and input schema from the function signature.

```python theme={"system"}
from typing import Annotated
from pydantic import Field
from fastmcp import FastMCP
from fastmcp.exceptions import ToolError

mcp = FastMCP(name="CalculatorServer")

@mcp.tool(
    name="find_products",
    description="Search the product catalog with optional category filtering.",
    tags={"catalog", "search"},
    timeout=30.0,
    annotations={"readOnlyHint": True},
)
def search_products(query: str, category: str | None = None) -> list[dict]:
    return [{"id": 2, "name": "Widget"}]

@mcp.tool
def process_image(
    image_url: Annotated[str, "URL of the image to process"],
    width: Annotated[int, Field(description="Target width", ge=1, le=2000)] = 800,
) -> dict:
    """Process an image with optional resizing."""
    ...

@mcp.tool
def divide(a: float, b: float) -> float:
    """Divide a by b."""
    if b == 0:
        raise ToolError("Division by zero is not allowed.")
    return a / b
```

**Supported type annotations:**

| Type | Example |
| - | - |
| Basic types | `int`, `float`, `str`, `bool` |
| Collections | `list[str]`, `dict[str, int]` |
| Optional | `float \| None`, `Optional[float]` |
| Constrained | `Literal["A", "B"]`, `Enum` |
| Pydantic models | `UserData` |

`ToolError` messages are always sent to clients. When `mask_error_details=True`, FastMCP masks other exceptions from clients.

#### Return structured output

When a tool returns a dataclass or a Pydantic model, FastMCP automatically generates `structuredContent` in the MCP response, giving the calling agent a typed schema to work with instead of free-form text. The `starter-mcp-server` demonstrates both styles; the examples below are simplified, so see `starter_mcp_server.py` for the full models.

> [tab] Dataclass
>
> ```python theme={"system"}
> from dataclasses import dataclass
> from fastmcp import FastMCP
>
> mcp = FastMCP(name="CatalogServer")
>
> @dataclass
> class PriceConversion:
>     original_price: float
>     currency: str
>     converted_price: float
>     target_currency: str
>     rate: float
>
> @mcp.tool
> def convert_price(price: float, target_currency: str) -> PriceConversion:
>     """Convert a product price from USD to another currency."""
>     rate = 0.92  # look up the real rate
>     return PriceConversion(
>         original_price=price,
>         currency="USD",
>         converted_price=round(price * rate, 2),
>         target_currency=target_currency.upper(),
>         rate=rate,
>     )
> ```

> [tab] Pydantic model
>
> ```python theme={"system"}
> from pydantic import BaseModel, Field
> from fastmcp import FastMCP
>
> mcp = FastMCP(name="CatalogServer")
>
> class ProductSummary(BaseModel):
>     id: int
>     title: str
>     price: float
>     category: str
>     in_stock: bool = True
>
> class CatalogPage(BaseModel):
>     products: list[ProductSummary]
>     total: int
>     page: int = Field(description="Current page number (1-based)")
>     page_size: int
>
> @mcp.tool
> async def get_catalog_page(page: int = 1, page_size: int = 5) -> CatalogPage:
>     """Get a page of products with structured metadata."""
>     products = [ProductSummary(id=1, title="Widget", price=9.99, category="Tools")]
>     return CatalogPage(products=products, total=len(products), page=page, page_size=page_size)
> ```

#### Request user input with elicitation

Elicitation lets a tool pause mid-execution to ask the user for additional information or confirmation before continuing — useful for confirmation dialogs, collecting missing inputs, or interactive workflows. The `starter-mcp-server` uses this in its `order_product` tool: it fetches a product, asks the user to confirm via a typed schema, and branches on the response. The example below is simplified — see `starter_mcp_server.py` for the production handler.

```python theme={"system"}
from fastmcp import FastMCP, Context
from fastmcp.server.elicitation import (
    AcceptedElicitation,
    DeclinedElicitation,
    CancelledElicitation,
)
from pydantic import BaseModel, Field

mcp = FastMCP(name="OrdersServer")

class OrderDetails(BaseModel):
    confirm: bool = Field(description="Whether to proceed with the order")
    quantity: int = Field(default=1, ge=1, le=100)
    shipping_address: str = Field(default="")

@mcp.tool
async def order_product(ctx: Context, product_id: int) -> dict:
    """Place an order after asking the user to confirm."""
    result = await ctx.elicit(
        message="Please confirm your order.",
        response_type=OrderDetails,
    )

    # Handle every response branch
    if isinstance(result, CancelledElicitation):
        return {"status": "cancelled"}
    if isinstance(result, DeclinedElicitation):
        return {"status": "declined"}

    order = result.data  # OrderDetails, available on AcceptedElicitation
    if not order.confirm:
        return {"status": "not_confirmed"}
    return {"status": "success", "quantity": order.quantity}
```

> [!WARNING]
>
> Elicitation requires **stateful sessions**, so it only works when the server runs with `MCP_STATELESS_HTTP=false` (or STDIO transport). With stateless HTTP there is no session to round-trip the user's response, and the elicitation call fails. This requirement is why the `starter-mcp-server` defaults `MCP_STATELESS_HTTP` to `false`.

#### Create from an OpenAPI spec

FastMCP can auto-generate an MCP server from any OpenAPI specification. Every endpoint becomes a tool that forwards requests to the underlying API. The `starter-mcp-server` uses this approach with the Platzi Fake Store API.

```python theme={"system"}
import httpx
import yaml
from fastmcp import FastMCP

with open("my-api-spec.yaml") as f:
    openapi_spec = yaml.safe_load(f)

client = httpx.AsyncClient(base_url="https://api.example.com")

mcp = FastMCP.from_openapi(
    openapi_spec=openapi_spec,
    client=client,
    name="My API Server",
)

if __name__ == "__main__":
    mcp.run()
```

#### Integrate a REST API as a tool

Instead of auto-generating from an OpenAPI spec, wrap any API call as a hand-written tool function:

```python theme={"system"}
import httpx
from fastmcp import FastMCP

mcp = FastMCP("API Tools Server")

@mcp.tool
async def get_payment_orders(status: str | None = None) -> dict:
    """Retrieve payment orders, optionally filtered by status."""
    async with httpx.AsyncClient() as client:
        params = {}
        if status:
            params["status"] = status
        response = await client.get(
            "https://api.example.com/client-api/v3/payment-orders",
            params=params,
            headers={"Authorization": "Bearer TOKEN"},
        )
        response.raise_for_status()
        return response.json()
```

#### Include and exclude tools

Use `RouteMap` to control which endpoints your MCP server exposes:

> [tab] Exclude routes
>
> ```python theme={"system"}
> from fastmcp import FastMCP
> from fastmcp.server.providers.openapi import RouteMap, MCPType
>
> mcp = FastMCP.from_openapi(
>     openapi_spec=spec,
>     client=client,
>     route_maps=[
>         RouteMap(pattern=r"^/admin/.*", mcp_type=MCPType.EXCLUDE),
>         RouteMap(tags={"internal"}, mcp_type=MCPType.EXCLUDE),
>         RouteMap(methods=["GET"], pattern=r"^/.*", mcp_type=MCPType.TOOL),
>         RouteMap(mcp_type=MCPType.EXCLUDE),
>     ],
> )
> ```
>
> FastMCP evaluates route maps in order. The first match wins.

> [tab] Allowlist (include only)
>
> ```python theme={"system"}
> mcp = FastMCP.from_openapi(
>     openapi_spec=spec,
>     client=client,
>     route_maps=[
>         RouteMap(methods=["GET"], pattern=r"^/client-api/v3/payment-orders$", mcp_type=MCPType.TOOL),
>         RouteMap(methods=["POST"], pattern=r"^/client-api/v3/payment-orders$", mcp_type=MCPType.TOOL),
>         RouteMap(mcp_type=MCPType.EXCLUDE),
>     ],
> )
> ```

> [tab] Tag-based visibility
>
> ```python theme={"system"}
> from fastmcp import FastMCP
>
> mcp = FastMCP("MyServer")
>
> @mcp.tool(tags={"admin"})
> def delete_all_orders() -> str:
>     return "Deleted"
>
> @mcp.tool(tags={"public"})
> def get_status() -> str:
>     return "OK"
>
> # Disable admin tools; clients only see get_status
> mcp.disable(tags={"admin"})
>
> # Or use allowlist mode
> mcp.enable(tags={"public"}, only=True)
>
> # Re-enable when needed
> mcp.enable(tags={"admin"})
> ```

**MCPType values:**

| Value | Description |
| - | - |
| `MCPType.TOOL` | Expose as an MCP Tool |
| `MCPType.RESOURCE` | Expose as an MCP Resource |
| `MCPType.RESOURCE_TEMPLATE` | Expose as a Resource Template |
| `MCPType.EXCLUDE` | Exclude from the MCP server entirely |

#### Forward client headers

When your MCP server proxies an authenticated API, forward headers from the MCP client request to upstream API calls. The `starter-mcp-server` includes this pattern for forwarding `Authorization` headers:

```python theme={"system"}
from typing import Any
import httpx
from fastmcp.server.dependencies import get_http_request

class HeaderForwardingClient(httpx.AsyncClient):
    """Forwards auth headers from the MCP client request to the upstream API."""

    async def send(self, request: httpx.Request, **kwargs: Any) -> httpx.Response:
        try:
            incoming = get_http_request()
            auth = incoming.headers.get("Authorization", "")
            if auth:
                request.headers["Authorization"] = auth
        except Exception:
            pass
        request.headers["Content-Type"] = "application/json"
        return await super().send(request, **kwargs)

api_client = HeaderForwardingClient(base_url="https://api.example.com")

mcp = FastMCP.from_openapi(
    openapi_spec=spec,
    client=api_client,
    name="My Authenticated API Server",
)
```

> [!WARNING]
>
> Header forwarding only works with HTTP transports such as `streamable-http`. It doesn't apply to STDIO transport because there is no HTTP request context.

#### Proxy bridge

The [Proxy Provider](https://gofastmcp.com/servers/providers/proxy) enables transport bridging, server aggregation, and gateway patterns:

> [tab] Transport bridging
>
> ```python theme={"system"}
> from fastmcp.server import create_proxy
>
> # Bridge HTTP server to local stdio
> http_proxy = create_proxy("http://example.com/mcp/sse", name="HTTP-to-stdio")
>
> if __name__ == "__main__":
>     http_proxy.run()  # Defaults to stdio
> ```

> [tab] Multi-server proxy
>
> ```python theme={"system"}
> from fastmcp.server import create_proxy
>
> config = {
>     "mcpServers": {
>         "weather": {
>             "url": "https://weather-api.example.com/mcp",
>             "transport": "http"
>         },
>         "calendar": {
>             "url": "https://calendar-api.example.com/mcp",
>             "transport": "http"
>         }
>     }
> }
>
> # Creates unified proxy with prefixed components:
> # - weather_get_forecast
> # - calendar_add_event
> composite = create_proxy(config, name="Composite")
> ```

#### Run the server

Start the server with transport, host, port, and path options:

```python theme={"system"}
if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",  # "stdio" (default) | "streamable-http"
        host="0.0.0.0",
        port=8557,
        path="/mcp",
        stateless_http=False,  # keep stateful for elicitation; set True for stateless deployments
    )
```

**Transport comparison:**

| Feature | STDIO | Streamable HTTP |
| - | - | - |
| Network access | No | Yes |
| Multiple clients | No | Yes |
| Production ready | Local only | Yes |
| Header forwarding | N/A | Yes |

Add a health check alongside the MCP endpoint:

```python theme={"system"}
from starlette.requests import Request
from starlette.responses import JSONResponse

@mcp.custom_route("/health", methods=["GET"])
async def health(request: Request) -> JSONResponse:
    return JSONResponse({"status": "ok"})
```

### Development

Use these commands while you change the server or add tools:

#### Run tests

Execute the test suite with pytest:

```bash theme={"system"}
uv sync --extra dev
uv run pytest
```

#### Build Docker image

Build a local image tag for the service:

```bash theme={"system"}
docker build -t starter-mcp-server:local .
```

### CI/CD

The `.github/workflows` directory defines these standard workflows:

* **PR checks**: Linting, testing, and validation
* **Build and publish**: Docker image creation on merge
* **Release**: Automated versioning and release notes

> [!NOTE]
>
> See **[CI/CD workflows](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/overview.md)** for pipeline details.

### Register in APIM via GitOps

After you deploy your FastMCP server, register it in APIM so the API gateway can route to it. This registration uses the [`agent-mcp-api`](https://github.com/bb-ecos-agbs/agent-mcp-api) template — a spec-only Maven project that produces an OpenAPI spec and Helm chart artifact for APIM deployment.

The deployment follows the GitOps pipeline: **GitHub PR → ArgoCD → Azure Service Operator (ASO) → APIM**.

1. **Use the agent-mcp-api template.** The [`agent-mcp-api`](https://github.com/bb-ecos-agbs/agent-mcp-api) project defines a complete MCP Streamable HTTP API spec for APIM (`POST /mcp`, `GET /mcp`, `DELETE /mcp`, `GET /health`, `GET /version`) with full JSON-RPC 2.0 envelope schemas and MCP session headers.

2. **Configure applications-live registration.** Register entries across **five files** in `applications-live` (`github.com/bb-ecos-<installation>/gc-<installation>-applications-live`) under `runtimes/<runtime>/apim/`:

   | File | Purpose |
   | - | - |
   | `apiversionsets.values.yaml` | Register the version set |
   | `backends.values.yaml` | Register the backend (upstream MCP server URL) |
   | `products.values.yaml` | Register the product with APIM policy (include `Accept: application/json, text/event-stream` for server-sent events (SSE) support) |
   | `subscriptions.values.yaml` | Register the subscription |
   | `apis/<your-mcp-api>.yaml` | ArgoCD `Application` manifest referencing the `agent-mcp-api` Helm chart |

3. **Set Helm values.** The ArgoCD `Application` manifest sets these Helm parameters, and pulls shared values in through `valueFiles`:

   ```yaml theme={"system"}
   helm:
     releaseName: YOUR_RELEASE_NAME
     parameters:
       - name: path
         value: UNIQUE_API_PATH           # Required. Must be unique per APIM instance — override to avoid a path collision
       - name: name
         value: API_RESOURCE_NAME         # Required. APIM API resource name; defaults to versionSet + major version
       - name: versionSet
         value: VERSION_SET_NAME          # Optional. Inferred from the Helm chart name; must match apiversionsets.values.yaml when set
       - name: azureName
         value: AZURE_RESOURCE_NAME       # Optional. Azure ARM resource name; defaults to name
       - name: displayName
         value: DISPLAY_NAME              # Optional. Defaults to the OpenAPI spec title (info.title)
     valueFiles:
       - $apps-live/runtimes/<runtime>/apim/apis/common.apim.values.yaml
   ```

   `apimArmId` (the Azure Resource Manager ID of the target APIM instance) is required by the chart, but you don't set it per API. It's defined centrally in `common.apim.values.yaml` and pulled in through `valueFiles`, so every API in the installation inherits it.

   The `path` defaults to `info.x-api-domain` and `info.x-api-service` from the OpenAPI spec (joined by a slash), or the Maven `artifactId` if those fields are absent. Override it with the `apim-helm-plugin.path` Maven property at build time, or the `path` Helm value at deploy time. The override is required when another API already uses the resolved path on the target APIM instance.

4. **Deploy and validate.** After ArgoCD picks up the merged PR, it deploys the API to APIM. Validate with a `tools/list` call through the APIM gateway:

   ```bash theme={"system"}
   curl -X POST https://api.<runtime>.<installation>.gcservices.io/<your-path>/<version>/mcp \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -H "api-key: YOUR_SUBSCRIPTION_KEY" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   ```

> [!NOTE]
>
> For the complete reference including APIM policy configuration, product setup, and end-to-end validation details, see **[ADR-MCP - Track 1 - PoC Validation](https://backbase.atlassian.net/wiki/spaces/BAAP/pages/6582501539)** on Confluence.

***

## Expose an API as an MCP server on APIM

APIM exposes your existing APIs as MCP servers without custom MCP server code. You select API operations in the Azure portal, and APIM handles MCP protocol translation, tool discovery, and invocation.

This approach is useful when you already have APIs provisioned in APIM and want to make them available to AI agents without building a separate FastMCP server.

### Prerequisites

Before you can expose an API as an MCP server on APIM:

1. **Ensure network connectivity.** The platform must have network connectivity to the target APIs. If it doesn't, [raise a ticket with the Service Desk](https://servicedesk.atlassian.backbase.com/servicedesk/customer/portal/3071) to request access.
2. **Upload your API spec to APIM** and register the API with `applications-live` (`github.com/bb-ecos-<installation>/gc-<installation>-applications-live` under `runtimes/<runtime>/apim`).

### High-level steps

Configure MCP in APIM through the portal:

1. Navigate to **APIs → MCP Servers (Preview)** in your APIM instance
2. Click **Create MCP Server → Expose an API as an MCP Server**
3. Select the API and operations to expose, starting with read-only endpoints
4. Configure APIM policies for security, including subscription key validation, rate limiting, and audit logging
5. Test with [MCP Inspector](https://github.com/modelcontextprotocol/inspector) or `curl`

> [!WARNING]
>
> **Known limitation**: POST operations with `requestBody.content` sections in the OpenAPI spec cause `/tools/list` to hang indefinitely. Remove or simplify the `requestBody.content` section in your OpenAPI spec before you expose the API via MCP. See the full guide for details.

> [!NOTE]
>
> For complete click-ops instructions that cover APIM policies, security configuration, rate limiting, audit logging, external MCP server proxying, and known issues, see the **[APIM MCP: click-ops guide](https://backbase.atlassian.net/wiki/spaces/BAAP/pages/5928290430)** on Confluence.

***

# MCP client

Connect to an MCP server from different types of clients, including programmatic Python clients, AI-native tools like Cursor and Claude Desktop, and AI agent frameworks like Agno.

> [card] [GitHub repository](https://github.com/bb-ecos-agbs/starter-mcp-client)
>
> View source code, releases, and issues

> [!NOTE]
>
> You need a running MCP server to connect to. See [MCP server](#mcp-server) to create one.

## Transport types

Before connecting, determine which transport your MCP server uses:

| Transport | Best for | How it works |
| - | - | - |
| **Streamable HTTP** | Production remote servers (recommended) | Client connects to an HTTP endpoint |
| **STDIO** | Local development, CLI servers | Client spawns the server as a sub-process |
| **SSE** | Legacy remote servers | HTTP with server-sent events (deprecated) |

> [!WARNING]
>
> SSE transport is deprecated by MCP. Always use **Streamable HTTP** for deployments. Use STDIO only for local development or CLI-based MCP servers such as `npx` and `uvx` packages.

## FastMCP client

[FastMCP](https://gofastmcp.com) provides a built-in `Client` class for connecting to any MCP server programmatically. The client infers the transport from what you pass to it.

> [tab] Basic usage
>
> ```python theme={"system"}
> import asyncio
> from fastmcp import Client
>
> async def main():
>     async with Client("https://example.com/mcp") as client:
>         tools = await client.list_tools()
>         for tool in tools:
>             print(f"  {tool.name}: {tool.description}")
>
>         result = await client.call_tool("get_payment_orders", {"status": "ACCEPTED"})
>         print(result)
>
> asyncio.run(main())
> ```

> [tab] With auth headers
>
> ```python theme={"system"}
> from fastmcp import Client
> from fastmcp.client.transports import StreamableHttpTransport
>
> transport = StreamableHttpTransport(
>     url="https://api.example.com/mcp",
>     headers={
>         "Authorization": "Bearer your-token",
>         "X-User-Context": "user-123",
>     },
> )
>
> async with Client(transport) as client:
>     tools = await client.list_tools()
>     result = await client.call_tool("list_orders", {})
> ```

> [tab] Multi-server client
>
> ```python theme={"system"}
> from fastmcp import Client
>
> config = {
>     "mcpServers": {
>         "payments": {
>             "url": "https://api.example.com:8557/mcp"
>         },
>         "accounts": {
>             "url": "https://api.example.com:8558/mcp"
>         },
>         "local_tools": {
>             "command": "python",
>             "args": ["./local_server.py"]
>         }
>     }
> }
>
> async with Client(config) as client:
>     orders = await client.call_tool("payments_get_payment_orders", {"status": "ACCEPTED"})
>     accounts = await client.call_tool("accounts_list_accounts", {})
> ```

## Cursor IDE

Cursor has built-in MCP support (v0.40+). Create `.cursor/mcp.json` in your project root:

> [tab] Streamable HTTP (remote)
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-mcp-server": {
>       "type": "streamableHttp",
>       "url": "https://api.example.com/mcp",
>       "headers": {
>         "Authorization": "Bearer your-token",
>         "X-User-Context": "user-123"
>       }
>     }
>   }
> }
> ```

> [tab] STDIO (local)
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-mcp-server": {
>       "command": "python",
>       "args": ["path/to/my_mcp_server.py"]
>     }
>   }
> }
> ```

Restart Cursor after adding the configuration. MCP servers only load at startup.

## Claude Desktop

Claude Desktop reads its MCP configuration from `claude_desktop_config.json`:

| OS | Path |
| - | - |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

> [tab] STDIO server
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-mcp-server": {
>       "command": "python",
>       "args": ["path/to/my_mcp_server.py"]
>     }
>   }
> }
> ```

> [tab] Streamable HTTP (via mcp-remote)
>
> Claude Desktop currently connects to remote MCP servers through a local proxy:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-mcp-server": {
>       "command": "npx",
>       "args": [
>         "mcp-remote",
>         "https://api.example.com/mcp"
>       ]
>     }
>   }
> }
> ```

## Agno agent

[Agno](https://docs.agno.com) is a Python framework for building AI agents with built-in MCP support through its `MCPTools` class.

> [tab] Streamable HTTP
>
> ```python theme={"system"}
> from agno.agent import Agent
> from agno.models.openai import OpenAIChat
> from agno.tools.mcp import MCPTools, StreamableHTTPClientParams
>
> params = StreamableHTTPClientParams(
>     url="http://api.example.com/mcp",
>     headers={
>         "Authorization": "Bearer your-token",
>         "X-User-Context": "user-123",
>     },
>     timeout=30,
>     terminate_on_close=True,
> )
>
> mcp_tools = MCPTools(
>     transport="streamable-http",
>     server_params=params,
>     timeout_seconds=60,
> )
> await mcp_tools.connect()
>
> agent = Agent(
>     name="My MCP Agent",
>     model=OpenAIChat(id="gpt-4o-mini"),
>     tools=[mcp_tools],
>     instructions=["Use the available tools to answer user questions."],
>     markdown=True,
> )
>
> await agent.aprint_response("Show me my payment orders")
> await mcp_tools.close()
> ```

> [tab] STDIO
>
> ```python theme={"system"}
> from agno.tools.mcp import MCPTools, StdioServerParameters
>
> server_params = StdioServerParameters(
>     command="python",
>     args=["my_mcp_server.py"],
>     env={"API_KEY": "secret"},
> )
>
> mcp_tools = MCPTools(transport="stdio", server_params=server_params)
> await mcp_tools.connect()
>
> agent = Agent(model=my_model, tools=[mcp_tools])
> await agent.aprint_response("What is the license for this project?")
> await mcp_tools.close()
> ```

> [tab] Multiple servers
>
> ```python theme={"system"}
> from agno.tools.mcp import MultiMCPTools
>
> mcp_tools = MultiMCPTools(
>     commands=[
>         "npx -y @openbnb/mcp-server-airbnb --ignore-robots-txt",
>         "npx -y @modelcontextprotocol/server-google-maps",
>     ],
>     env={**os.environ, "GOOGLE_MAPS_API_KEY": os.getenv("GOOGLE_MAPS_API_KEY")},
> )
> await mcp_tools.connect()
>
> agent = Agent(model=my_model, tools=[mcp_tools])
> ```

## Pass headers to MCP servers

How you pass authentication headers depends on your client type:

> [tab] FastMCP client
>
> ```python theme={"system"}
> from fastmcp import Client
> from fastmcp.client.transports import StreamableHttpTransport
>
> transport = StreamableHttpTransport(
>     url="https://api.example.com/mcp",
>     headers={"Authorization": "Bearer your-token"},
> )
>
> async with Client(transport) as client:
>     result = await client.call_tool("get_orders", {})
> ```

> [tab] Cursor IDE
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-server": {
>       "type": "streamableHttp",
>       "url": "https://api.example.com/mcp",
>       "headers": {
>         "Authorization": "Bearer your-token",
>         "X-User-Context": "user-123",
>         "api-key": "your-api-key"
>       }
>     }
>   }
> }
> ```

> [tab] Claude Desktop
>
> For STDIO servers, pass secrets via environment variables:
>
> ```json theme={"system"}
> {
>   "mcpServers": {
>     "my-server": {
>       "command": "python",
>       "args": ["my_server.py"],
>       "env": {
>         "API_TOKEN": "your-token"
>       }
>     }
>   }
> }
> ```

> [tab] Agno
>
> When you expose your agent through a FastAPI endpoint, extract headers from the incoming request:
>
> ```python theme={"system"}
> from agno.tools.mcp import MCPTools, StreamableHTTPClientParams
>
> async def create_mcp_tools(headers: dict[str, str]) -> MCPTools:
>     params = StreamableHTTPClientParams(
>         url="https://api.example.com/mcp",
>         headers=headers,
>     )
>     tools = MCPTools(
>         transport="streamable-http",
>         server_params=params,
>         timeout_seconds=60,
>     )
>     await tools.__aenter__()
>     return tools
> ```

***

## Next steps

From here you can extend agents, teams, knowledge, and pipelines:

* **[Starter Agent](https://agenticbanking.backbase.io/agentic-ai/starter-kits/starter-agent.md)**: Start with basic agent patterns
* **[Multi-Agent](https://agenticbanking.backbase.io/agentic-ai/starter-kits/multi-agent.md)**: Build agent teams
* **[Knowledge Agent](https://agenticbanking.backbase.io/agentic-ai/starter-kits/knowledge-agent.md)**: Add RAG capabilities
* **[BB AI SDK](https://agenticbanking.backbase.io/agentic-ai/bb-ai-sdk/overview.md)**: AI Gateway and observability
* **[CI/CD workflows](https://agenticbanking.backbase.io/agentic-ai/ci-cd-workflows/overview.md)**: Pipeline details
