MCP Gateway | Solace Agent Mesh
Description: This tutorial walks you through setting up the MCP Gateway, which exposes Solace Agent Mesh agents as a Model Context Protocol (MCP) server. This allows MCP-compatible client (such as Claude Desktop, MCP Inspector, or custom applications) to interact with Solace Agent Mesh agents through a standardized interface.

Skip to main content

# MCP Gateway

This tutorial walks you through setting up the MCP Gateway, which exposes Solace Agent Mesh agents as a Model Context Protocol (MCP) server. This allows MCP-compatible client (such as Claude Desktop, MCP Inspector, or custom applications) to interact with Solace Agent Mesh agents through a standardized interface.

Learn about gateways

Read about Gateways before you start this tutorial.

## Overview​

The MCP Gateway adapter:

- Dynamically discovers agents from the Solace Agent Mesh agent registry
- Creates MCP tools automatically based on agent skills
- Streams responses in real-time back to MCP clients
- Handles files intelligently by returning inline content or resource links based on size
- Maintains session isolation ensuring secure multi-client access

## Setting Up the Environment​

First, you need to install Agent Mesh and the Agent Mesh CLI, and then create a new Agent Mesh project.

## Adding the MCP Gateway Plugin​

Once you have your project set up, add the MCP Gateway plugin:

    sam plugin add my-mcp-gateway --plugin sam-mcp-server-gateway-adapter

You can use any name for your gateway. In this tutorial we use `my-mcp-gateway`.

This command:

1. Installs the `sam-mcp-server-gateway-adapter` plugin.
2. Creates a gateway configuration named `my-mcp-gateway` in your `configs/gateways/` directory.

## Configuration​

You can customize the gateway by editing the `configs/gateways/my-mcp-gateway.yaml` file.

### Key Configuration Options​

    adapter_config:
      # Server identity
      mcp_server_name: "Solace Agent Mesh MCP Gateway"
      mcp_server_description: "Access to Solace Agent Mesh agents via MCP"

      # Transport: "http" or "stdio"
      transport: http

      # HTTP settings (when transport = "http")
      host: "0.0.0.0"
      port: 8090

      # Authentication
      default_user_identity: "mcp_user"

      # Streaming
      stream_responses: true

      # Task timeout (in seconds)
      task_timeout_seconds: 300  # 5 minutes default

      # File size thresholds for inline content
      inline_image_max_bytes: 5242880      # 5MB
      inline_audio_max_bytes: 10485760     # 10MB
      inline_text_max_bytes: 1048576       # 1MB
      inline_binary_max_bytes: 524288      # 512KB

      # Tool filtering (optional)
      include_tools: []  # Include only these tools (empty = all)
      exclude_tools: []  # Exclude these tools

Host and Port

The `host` and `port` settings defined above needs to be exposed in your deployment environment (e.g., Docker, Kubernetes) so that MCP clients can connect.

The path `/mcp` should point to the gateway service address.

MCP Server Gateway with Authentication

If you have authentication enabled in your gateway, you'd need to expose and map the following routes to your gateway service address:

- `/oauth/authorize`
- `/oauth/callback`
- `/oauth/token`
- `/oauth/register`
- `/.well-known/oauth-authorization-server`

Example for Kubernetes Service and Ingress configuration:

    apiVersion: v1
    kind: Service
    metadata:
      name: solace-agent-mesh-mcp-service
    spec:
      selector:
        app: solace-agent-mesh
      type: ClusterIP
      ports:
        - name: http
          protocol: TCP
          targetPort: http-mcp
          port: 8090

    ---

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: solace-agent-mesh-ingress
      labels:
        app: solace-agent-mesh-ingress
    spec:
      ingressClassName: alb
      rules:
      - http:
          paths:
          - path: /mcp
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090
          - path: /oauth/authorize
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090
          - path: /oauth/callback
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090
          - path: /oauth/token
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090
          - path: /oauth/register
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090
          - path: /.well-known/oauth-authorization-server
            pathType: Prefix
            backend:
              service:
                name: solace-agent-mesh-mcp-service
                port:
                  number: 8090

## Running the MCP Gateway​

To run the MCP Gateway, use the following command:

    sam run configs/gateways/my-mcp-gateway.yaml

The gateway starts and automatically:

1. Queries the agent registry for available agents.
2. Creates MCP tools for each agent skill.
3. Starts listening for MCP client connections.

## Connecting MCP Clients​

To connect to Solace Agent Mesh via MCP, configure your MCP client (e.g., Claude Desktop) to point to the gateway URL:

    http://<gateway-host>:<gateway-port>/mcp

Make sure to select the appropriate transport (HTTP) and enable OAuth2.0 authentication if configured.

## How It Works​

### Architecture​

### Tool Naming​

Each agent skill becomes an MCP tool with the naming pattern:

    {agent_name}_{skill_name}

For example:

- Agent: `WeatherAgent`, Skill: `Get Forecast` → Tool: `weather_agent_get_forecast`
- Agent: `CodeAssistant`, Skill: `Review Code` → Tool: `code_assistant_review_code`

Tool names are automatically sanitized to be valid MCP identifiers (lowercase, alphanumeric with underscores).

### Dynamic Agent Discovery​

As agents join and leave the Solace Agent Mesh mesh:

1. Agent Joins: When a new agent publishes its AgentCard.

   - The adapter detects the new agent
   - Registers new MCP tools for the agent's skills
   - FastMCP sends `tools/list_changed` notification to connected clients
   - MCP clients automatically refresh their tool list

2. Agent Leaves: When an agent is removed.

   - The adapter detects the removal
   - Removes the agent's tools from the MCP server
   - FastMCP notifies clients of the change
   - Stale tools disappear from the client's tool list

## Tool Filtering​

The MCP adapter supports filtering which agent tools are exposed through the MCP server. This is useful for:

- Limiting tool visibility to specific agents or skills
- Hiding debug/internal tools from clients
- Creating specialized MCP servers with curated tool sets

### Configuration​

    adapter_config:
      # Include only data-related tools
      include_tools:
        - "data_.*"           # Regex: any tool starting with "data_"
        - "fetch_user_info"   # Exact: specific tool name

      # Exclude debug tools and test agents
      exclude_tools:
        - ".*_debug"          # Regex: any tool ending with "_debug"
        - "TestAgent"         # Exact: specific agent name

### How Filtering Works​

What Gets Checked: Filters check against all three of:

1. Original agent name (e.g., `"DataAgent"`)
2. Original skill name (e.g., `"Fetch User"`)
3. Final sanitized tool name (e.g., `"data_agent_fetch_user"`)

Pattern Types: The adapter automatically detects pattern types:

- Regex patterns: Contain special characters like `.*+?[]{}()^$|\`
- Exact matches: Plain strings without special characters

Priority Order (highest to lowest):

1. Exclude exact match - If pattern matches exactly, tool is rejected
2. Include exact match - If pattern matches exactly, tool is accepted
3. Exclude regex match - If regex pattern matches, tool is rejected
4. Include regex match - If regex pattern matches, tool is accepted
5. Default - If `include_tools` is empty, accept; otherwise reject

### Filter Examples​

Example 1: Include only specific tools

    include_tools:
      - "weather_agent_.*"                 # All tools from weather_agent
      - "code_assistant_review_code"       # One specific tool
    exclude_tools: []

Example 2: Exclude debug/internal tools

    include_tools: []          # Empty = include all
    exclude_tools:
      - ".*_debug"             # Exclude all debug tools
      - ".*_internal"          # Exclude all internal tools
      - "TestAgent"            # Exclude entire test agent

## File Handling​

The MCP gateway intelligently returns files based on their type and size:

### Content Type Strategy​

Images (`image/*` MIME types):

- Small (< 5MB): Returned inline as `ImageContent` with base64 encoding
- Large (≥ 5MB): Returned as `ResourceLink` for separate download

Audio (`audio/*` MIME types):

- Small (< 10MB): Returned inline as `AudioContent` with base64 encoding
- Large (≥ 10MB): Returned as `ResourceLink`

Text Files:

- Small (< 1MB): Returned as `EmbeddedResource` with `TextResourceContents`
- Large (≥ 1MB): Returned as `ResourceLink`

Other Binary Files:

- Small (< 512KB): Returned as `EmbeddedResource` with `BlobResourceContents`
- Large (≥ 512KB): Returned as `ResourceLink`

### Mixed Content Responses​

When a tool response includes both text and files, the MCP gateway returns a list of content blocks:

    [
        TextContent(type="text", text="Here is the result..."),
        ImageContent(type="image", data="base64...", mimeType="image/png"),
        ResourceLink(type="resource_link", uri="artifact://session/report.pdf", ...)
    ]

## Troubleshooting​

### Issue: No tools appearing in MCP client​

#### Possible Solutions:​

- Check that agents are registered in the agent registry.
- Verify agents have skills defined in their AgentCard.
- Check gateway logs for tool registration messages.
- Review tool filter configuration if using `include_tools` or `exclude_tools`.
- If authentication is enabled, ensure RBAC permissions are set correctly.

### Issue: Connection refused​

#### Possible Solutions:​

- Verify the MCP server is running (check logs).
- Ensure the configured port is not in use.
- Check firewall settings (for HTTP transport).

### Issue: Files not appearing or timing out​

#### Possible Solutions:​

- Check file size thresholds in configuration.
- Verify artifact service is configured correctly.
- Review session management in logs.