mcp-integration.md
1 --- 2 title: MCP Integration 3 sidebar_position: 10 4 --- 5 6 # MCP Integration 7 8 This tutorial walks you through the process of integrating a Model Context Protocol (MCP) Server into Agent Mesh. 9 10 :::info[Learn about agents] 11 You should have an understanding of agents in Agent Mesh. For more information, see [Agents](../../components/agents.md). 12 ::: 13 14 Agent Mesh now provides **native MCP support** through the framework itself. No additional plugins are required - you can connect to MCP servers directly by configuring your agent YAML file with MCP tools. 15 16 MCP integration allows your agents to connect to external MCP servers and use their tools, resources, and prompts seamlessly within the A2A protocol ecosystem. 17 18 ## Setting Up the Environment 19 20 You must [install Agent Mesh and the CLI](../../installing-and-configuring/installation.md), and then [create a new Agent Mesh project](../../installing-and-configuring/run-project.md). 21 22 For this tutorial using the filesystem MCP server, you also need Node.js and NPM installed. 23 24 ## Adding MCP Tools to an Agent 25 26 MCP integration is accomplished by adding MCP tools directly to your agent configuration. There are three main connection types supported: 27 28 ### 1. Stdio Connection (Local MCP Servers) 29 30 This is the most common method for connecting to MCP servers that run as local processes: 31 32 :::info[Install node package] 33 You must install node package @modelcontextprotocol/server-filesystem securely in your local system. 34 35 You must set the `command` parameter to your local path that points to the `mcp-server-filesystem` binary executable. 36 ::: 37 38 ```yaml 39 tools: 40 - tool_type: mcp 41 connection_params: 42 type: stdio 43 command: "./node_modules/.bin/mcp-server-filesystem" 44 args: 45 - "/tmp/samv2" 46 ``` 47 48 ### 2. SSE Connection (Remote MCP Servers) 49 50 For connecting to remote MCP servers using Server-Sent Events: 51 52 ```yaml 53 tools: 54 - tool_type: mcp 55 connection_params: 56 type: sse 57 url: "https://mcp.example.com/v1/sse" 58 headers: 59 Authorization: "Bearer ${MCP_AUTH_TOKEN}" 60 ``` 61 62 ### 3. StreamableHTTP Connection (Remote MCP Servers) 63 64 For connecting to remote MCP servers using Server-Sent Events: 65 66 ```yaml 67 tools: 68 - tool_type: mcp 69 connection_params: 70 type: streamable-http 71 url: "https://mcp.example.com:<port>/mcp/message" 72 headers: 73 Authorization: "Bearer ${MCP_AUTH_TOKEN}" 74 ``` 75 76 ### 4. Docker Connection (Containerized MCP Servers) 77 78 For running MCP servers in Docker containers: 79 80 ```yaml 81 tools: 82 - tool_type: mcp 83 connection_params: 84 type: stdio 85 command: "docker" 86 args: 87 - "run" 88 - "-i" 89 - "--rm" 90 - "-e" 91 - "API_KEY" 92 - "mcp-server-image:latest" 93 environment_variables: 94 API_KEY: ${MY_API_KEY} 95 ``` 96 97 ## Complete Example: Filesystem MCP Agent 98 99 Here is a complete example of an agent that uses the filesystem MCP server: 100 101 :::info[Install node package] 102 You must install node package @modelcontextprotocol/server-filesystem securely in your local system. 103 104 You must set the `command` parameter to your local path that points to the `mcp-server-filesystem` binary executable. 105 ::: 106 107 ```yaml 108 # configs/agents/filesystem_agent.yaml 109 log: 110 stdout_log_level: INFO 111 log_file_level: DEBUG 112 log_file: filesystem_agent.log 113 114 !include ../shared_config.yaml 115 116 apps: 117 - name: filesystem_mcp_agent_app 118 app_base_path: . 119 app_module: solace_agent_mesh.agent.sac.app 120 broker: 121 <<: *broker_connection 122 123 app_config: 124 namespace: ${NAMESPACE} 125 supports_streaming: true 126 agent_name: "FileSystemAgent" 127 display_name: "File System" 128 model: *general_model 129 model_provider: 130 - "general" 131 132 instruction: | 133 You can interact with the local filesystem using MCP tools. 134 Use the available tools to read, write, and manage files as requested. 135 136 tools: 137 - tool_type: mcp 138 connection_params: 139 type: stdio 140 command: "./node_modules/.bin/mcp-server-filesystem" 141 args: 142 - "/tmp/samv2" 143 - tool_type: builtin-group 144 group_name: "artifact_management" 145 146 session_service: *default_session_service 147 artifact_service: *default_artifact_service 148 149 # Agent discovery and communication 150 agent_card: 151 description: "An agent that interacts with the local filesystem via MCP." 152 defaultInputModes: ["text"] 153 defaultOutputModes: ["text", "file"] 154 skills: [] 155 156 agent_card_publishing: { interval_seconds: 10 } 157 agent_discovery: { enabled: true } 158 inter_agent_communication: 159 allow_list: ["*"] 160 request_timeout_seconds: 30 161 ``` 162 163 ## Configuration Options 164 165 ### Tool Filtering 166 167 You can control which tools from an MCP server are available to your agent using three mutually exclusive filtering options. 168 169 :::info[Install node package] 170 The examples below use the filesystem MCP server. You must install node package @modelcontextprotocol/server-filesystem securely in your local system and set the `command` parameter to your local path that points to the `mcp-server-filesystem` binary executable. 171 ::: 172 173 #### Single Tool (tool_name) 174 175 Use `tool_name` to expose only a single specific tool: 176 177 ```yaml 178 tools: 179 - tool_type: mcp 180 tool_name: "read_file" # Only expose the read_file tool 181 connection_params: 182 type: stdio 183 command: "./node_modules/.bin/mcp-server-filesystem" 184 args: 185 - "/tmp/samv2" 186 ``` 187 188 #### Allow List 189 190 Use `allow_list` to expose multiple specific tools: 191 192 ```yaml 193 tools: 194 - tool_type: mcp 195 allow_list: # Only expose these tools 196 - read_file 197 - write_file 198 - list_directory 199 connection_params: 200 type: stdio 201 command: "./node_modules/.bin/mcp-server-filesystem" 202 args: 203 - "/tmp/samv2" 204 ``` 205 206 #### Deny List 207 208 Use `deny_list` to expose all tools except specific ones: 209 210 ```yaml 211 tools: 212 - tool_type: mcp 213 deny_list: # Expose all tools EXCEPT these 214 - delete_file 215 - move_file 216 connection_params: 217 type: stdio 218 command: "./node_modules/.bin/mcp-server-filesystem" 219 args: 220 - "/tmp/samv2" 221 ``` 222 223 :::warning[Mutual Exclusivity] 224 The `tool_name`, `allow_list`, and `deny_list` options are mutually exclusive. You can only use one of these filtering options per MCP tool configuration. 225 ::: 226 227 ### Environment Variables 228 229 Pass environment variables to MCP servers using the `environment_variables` block: 230 231 ```yaml 232 tools: 233 - tool_type: mcp 234 connection_params: 235 type: stdio 236 command: "my-mcp-server" 237 environment_variables: 238 API_KEY: ${MY_API_KEY} 239 DEBUG_MODE: "true" 240 CONFIG_PATH: "/etc/myconfig" 241 ``` 242 243 ### SSL/TLS Configuration 244 245 For remote MCP connections (SSE and Streamable HTTP), you can configure SSL/TLS settings to connect to servers with self-signed certificates or custom CA bundles. 246 247 #### Disable SSL Verification (Development Only) 248 249 :::warning[Security Risk] 250 Disabling SSL verification should only be used in development environments. Never disable SSL verification in production. 251 ::: 252 253 ```yaml 254 tools: 255 - tool_type: mcp 256 connection_params: 257 type: sse 258 url: "https://dev-mcp-server.local/sse" 259 ssl_config: 260 verify: false 261 ``` 262 263 #### Custom CA Certificate 264 265 For servers using certificates signed by a private CA: 266 267 ```yaml 268 tools: 269 - tool_type: mcp 270 connection_params: 271 type: sse 272 url: "https://internal-mcp.example.com/sse" 273 ssl_config: 274 ca_bundle: "/path/to/ca-certificate.pem" 275 ``` 276 277 :::note 278 The `ssl_config` option only applies to remote connections (`sse` and `streamable-http`). It has no effect on `stdio` connections which run as local processes. 279 ::: 280 281 ## Running Your MCP-Enabled Agent 282 283 1. **Create the working directory** (for filesystem example): 284 ```sh 285 mkdir -p /tmp/samv2 286 echo "Hello MCP!" > /tmp/samv2/test.txt 287 ``` 288 289 2. **Set required environment variables**: 290 ```sh 291 export NAMESPACE="myorg/dev" 292 export SOLACE_BROKER_URL="ws://localhost:8008" 293 # ... other Solace broker settings 294 ``` 295 296 3. **Run the agent**: 297 ```sh 298 sam run configs/agents/filesystem_agent.yaml 299 ``` 300 301 ## How MCP Integration Works 302 303 When your agent starts: 304 305 1. **Connection**: The framework establishes a connection to the MCP server using the specified connection parameters 306 2. **Discovery**: It queries the MCP server for available tools, resources, and prompts 307 3. **Registration**: Available capabilities are registered as agent tools. 308 4. **Communication**: The agent can use these tools through the standard A2A protocol, with the framework handling MCP protocol translation 309 310 311 ## Testing Your MCP Integration 312 313 Once your MCP-enabled agent is running, you can test it through any gateway in your project (such as the Web UI gateway): 314 315 1. **Access your gateway** (for example, Web UI at `http://localhost:8000`) 316 2. **Send a request** to test the MCP functionality: 317 - "List the files in the directory" 318 - "Create a simple text file with some content" 319 - "Read the contents of test.txt" 320 321 The agent uses the MCP tools to interact with the filesystem and provide responses through the A2A protocol.