Skip to main content
In addition to MeshAgent Tools, agents can also use external tools through OpenAI Connectors and Model Context Protocol (MCP) servers.
  • OpenAI Connectors: OpenAI-maintained MCP wrappers for third party services that don’t have official MCP servers (Gmail, Google Drive, Outlook, Microsoft Teams, Dropbox etc.). Using these connectors requires OAuth client registration and authorization with the provider.
  • Remote MCP servers: Any MCP server operated by you or a third party. You provide the server URL and any required authentication details, and the agent can call the server’s MCP tools.

​
Two ways to use MCP Tools & OpenAI Connectors in MeshAgent

​
1. User-Toggleable Tools (Per-Message)

Use this when you want users to choose tools on demand, per message or per conversation — similar to ChatGPT/Claude tool toggles. Examples
  • “Enable Google Drive only for this question”
  • “Use Teams for this message, but not the next”
  • Avoid tool bloat by not attaching dozens of tools permanently
How it works
  • You deploy MCP servers / connectors as services so they’re available in a room/project
  • Your agent is configured to accept MCP tools dynamically
  • Your UI lets users toggle tools on/off, and passes the selection to the agent
Best for
  • ChatGPT-style experiences
  • Reducing agent bloat by deploying multiple tools and toggling them on/off as needed during interactive agent sessions
  • Best when tools require explicit approval

​
2. Always-On Tools (Agent-Owned)

Use this when your agent should always have access to specific tools. Examples
  • A support agent that always needs ticketing tools
  • A repo assistant that always needs GitHub MCP tools
  • A bot that always reads from a single internal system
How it works
  • You attach MCP tools to the agent via the SDK (toolkits), or deploy an agent/service that includes them.
  • The agent will always have these tools available on every turn.
Best for
  • Agents that routinely need access to certain tools
  • Background agents who should have access to the tool by default
  • Cases when users should not choose tools manually
In both cases, MeshAgent talks to OpenAI via the OpenAIResponsesAdapter. This adapter gathers the toolkits available to the agent on that turn, manages tool execution, streaming responses, and returning the final result. Tool lists are rebuilt on every user message by merging always-on toolkits with any user-selected toolkits for that turn. For the full flow see Tool Usage Patterns.

​
User-Toggleable Tools (Per-Message)

This section shows you how to let users dynamically enable/disable OpenAI Connectors and MCP servers per conversation or message — similar to how ChatGPT and Claude let you toggle tools on and off.

​
When to use user-toggleable tools

Use this mode when you want users to control which capabilities are available on demand. This helps reduce agent bloat by avoiding deployments where each agent has a different permutation of tools. If an agent should always have specific capabilities, you can use the always-on approach instead (attach tools via toolkits).
Note: Even with user-toggleable tools, users can enable multiple (or even all) tools at once. The difference is that tools are opt-in per message, rather than permanently attached to the agent.
User-toggleable tools are supported automatically when you run the CLI ChatBot with flags like --mcp. This enables per-message tool selection and is supported in MeshAgent Studio and Powerboards automatically. You can implement the same pattern when building agents with the MeshAgent SDK by adding toolkit builders (e.g. MCPToolkitBuilder()) and passing the user’s tool selection to the agent each turn.

​
How user-toggleable tools work

User-toggleable MCP tool selection has three pieces:
  1. Deployed services that expose MCP servers or OpenAI Connectors
  2. An agent configured to accept MCP tools dynamically
  3. A UI that displays available services and lets users toggle them on/off
MeshAgent Studio and Powerboards handle the UI integration automatically.

​
Example 1: Dynamic MCP Tools in MeshAgent

​
Step 1: Create the Service YAML

First you need to package and deploy a project or room service for the MCP Servers or OpenAI Connectors you want the agent to have access to. You can do this by defining a service yaml file and deploying the service using the MeshAgent CLI. For example, let’s deploy the DeepWiki MCP Server which provides tools for reading public GitHub repositories (no authentication required). To do so we’ll create a YAML file that defines the service and deploy it with the CLI. Create a meshagent.yaml file for the MCP DeepWiki service. 
kind: Service
version: v1
metadata:
  name: mcp-deepwiki
  description: "Expose DeepWiki MCP server"
ports:
- num: 443 # SSL is 443 for non SSL it's 80
  type: http
  endpoints:
  - path: /mcp # url + path are appended together
    mcp:
      label: "mcp-deepwiki"
      description: "MCP DeepWiki Tools"
external:
  url: "https://mcp.deepwiki.com"

​
Step 2: Deploy the service

meshagent service create --file="meshagent.yaml"  --room=quickstart

​
Step 3: Configure your agent to accept MCP tools

Your agent needs to be configured with MCPToolkitBuilder() so it can accept tools selected by the user. The CLI ChatBot does this automatically with the --mcp flag. 
meshagent chatbot join --room=quickstart --agent-name=agent --mcp
Note: The CLI ChatBot also supports other dynamic toolkits like --web-search and --storage that work similarly. They add toolkit builders so users can enable/disable these capabilities per message.
For custom ChatBots, you must add it manually:
python
from meshagent.openai.tools.responses_adapter import MCPToolkitBuilder

class MyChatBot(ChatBot):
    def get_toolkit_builders(self):
        builders = super().get_toolkit_builders()
        builders.append(MCPToolkitBuilder())  # Add this!
        return builders

​
Step 4: Test in MeshAgent Studio

Go to MeshAgent Studio and try out the ChatBot, you’ll be able to turn on the MCP DeepWiki tool from the UI. The UI automatically discovers and displays available services and shows them as selectable tools that users can toggle on/off. If you’re building a custom UI, you’ll need to implement similar discovery and selection functionality.

​
Example 2: Create a MeshAgent Service for an OpenAI Connector

OpenAI Connectors require OAuth authentication. You’ll need to register an OAuth client with the service provider first. See OpenAI’s documentation for additional instructions. Once you register your OAuth API client you can create and deploy the service just like we did for the MCP Server.

​
Step 1: Create the Service YAML

kind: Service
version: v1
metadata:
  name: microsoft-teams-connector
  description: "Expose Microsoft Teams via OpenAI Connector"
ports:
- num: "*"
  type: http
  endpoints:
  - path: /
    mcp:
      label: "microsoft-teams-connector"
      description: "OpenAI Connector for Microsoft Teams"
      openai_connector_id: "connector_microsoftteams"
      oauth:
        client_id: "YOUR_CLIENT_ID"
        client_secret: "..."
        authorization_endpoint: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize"
        token_endpoint: "https://login.microsoftonline.com/common/oauth2/v2.0/token"
        no_pkce: false                    # Optional: depends on if pkce is used
        scopes: ["User.Read", "Chat.Read", "ChannelMessage.Read.All"]
external: {}

​
Step 2: Deploy the service

meshagent service create --file="meshagent.yaml"  --room=quickstart

​
Step 3: Start the CLI ChatBot with MCP Enabled

meshagent chatbot join --room=quickstart --agent-name=agent --mcp
# make sure room matches room you deployed to if deployed as a room service

​
Step 4: Use It in MeshAgent Studio

Open MeshAgent Studio, go to your room, and you’ll see “Microsoft Teams” as a toggleable tool. Enable it to let the agent read Teams messages!

​
Example 3: Always-on MCP Tools with MeshAgent

​
Step 1: Define a ChatBot with MCP Tools

Let’s create a ChatBot that can use the public DeepWiki MCP Server which does not require an access token or OAuth. For this ChatBot we’ll define:
  • A Toolkit: a collection of related tools the agent can use
  • An MCPTool: connects to an MCP server
  • MCPConfig: configuration for the MCP connection
  • MCPServer: the actual server details (URL, authentication details)
import asyncio
import logging
from meshagent.tools import Toolkit
from meshagent.agents.chat import ChatBot
from meshagent.openai import OpenAIResponsesAdapter
from meshagent.openai.tools.responses_adapter import MCPConfig, MCPServer, MCPTool
from meshagent.api.services import ServiceHost
from meshagent.otel import otel_config

otel_config(service_name="mcp-deepwiki-chatbot")
log = logging.getLogger(__name__)
service = ServiceHost()

@service.path(path="/mcp-deepwiki-chatbot", identity="mcp-deepwiki-chatbot")
class MCPChatbot(ChatBot):
    def __init__(self):
        super().__init__(
            title="ChatBot that can use DeepWiki MCP Server",
            description="An agent that can use the DeepWiki MCP server",
            rules=["you are an assistant for trying out MCP servers"],
            llm_adapter=OpenAIResponsesAdapter(parallel_tool_calls=True),
            auto_greet_message="What can I help you with?",
            toolkits=[
                Toolkit(
                    name="mcp-deepwiki-toolkit",
                    tools=[
                        MCPTool(
                            config=MCPConfig(
                                name="mcp",
                                servers=[
                                    MCPServer(
                                        server_label="mcp",
                                        server_url="https://mcp.deepwiki.com/mcp",
                                    )
                                ],
                            )
                        )
                    ],
                )
            ],
            labels=["tasks", "mcp"],
        )


asyncio.run(service.run())

​
Step 2: Run and test the agent

Run it locally and try it in MeshAgent Studio:
bash
meshagent service run "main.py" --room=quickstart
From MeshAgent Studio, enter quickstart, and start talking to the agent. Ask it about public GitHub repositories and it will use the DeepWiki MCP tools to respond. For example you can ask “What’s in the README on the Pydantic AI repository?”.

​
Step 3: Package and deploy the agent

To deploy your SDK MCP ChatBot permanently, you’ll package your code with a meshagent.yaml file that defines the service configuration and a container image that MeshAgent can run. For full details on the service spec and deployment flow, see Packaging Services and Deploying Services. MeshAgent supports two deployment patterns for containers:
  1. Runtime image + code mount (recommended): Use a pre-built MeshAgent runtime image (like python-sdk-slim) that contains Python and all MeshAgent dependencies. Mount your lightweight code-only image on top. This keeps your code image tiny (~KB), eliminates dependency installation time, and allows your service to start quickly.
  2. Single Image: Bundle your code and all dependencies into one image. This is good when you need to install additional libraries, but can result in larger images and slower pulls. If you build your own images we recommend optimizing them with eStargz.
This example demonstrates approach #1 with a code-only image. The default YAML points at the public python-docs-examples image so you can still run the documentation examples without building your own images. If you want to build and push your own code image, follow the steps below and update the image mount section of the meshagent.yaml file. Prepare your project structure This example organizes the agent code and configuration in the same folder, making each agent self-contained: 
your-project/
├── Dockerfile                    # Shared by all samples
├── mcp_chatbot/
│   ├── mcp_chatbot.py
│   └── meshagent.yaml            # Config specific to this sample
└── another_sample/               # Other samples follow same pattern
    ├── another_sample.py
    └── meshagent.yaml
Note: If you’re building a single agent, you only need the mcp_chatbot/ folder. The structure shown supports multiple samples sharing one Dockerfile.
Step 3a: Build a Docker container Create a scratch Dockerfile and copy the files you want to run. This creates a minimal image containing only your code files. 
FROM scratch

COPY . /
Build and push the image with docker buildx:
bash
docker buildx build . \
  -t "<REGISTRY>/<NAMESPACE>/<IMAGE_NAME>:<TAG>" \
  --platform linux/amd64 \
  --push
Note: Building from the project root copies your entire project structure into the image. For a single agent, this is fine - your image will just contain one folder. For multi-agent projects, all agents will be in one image, but each can deploy independently using its own meshagent.yaml.
Step 3b: Package the agent Define the service configuration in a meshagent.yaml file. This service will have a container section that references:
  • Runtime image: The MeshAgent Python SDK image with all dependencies
  • Code mount: Your code-only image mounted at /src
  • Command path: Points to your sample’s specific location
kind: Service
version: v1
metadata:
  name: mcp-deepwiki-chatbot
  description: "Expose a ChatBot with access to DeepWiki MCP server"
agents:
  - name: assistant
    description: "Conversational agent for the room"
    annotations:
      meshagent.agent.type: "ChatBot"
ports:
- num: "*" 
  type: http
  liveness: "/"
  endpoints:
  - path: /mcp-deepwiki-chatbot
    meshagent:
      identity: "MCP DeepWiki ChatBot"
      # api: if you need to use secrets/OAuth with the agent you can add those permissions here
container:
  image: "us-central1-docker.pkg.dev/meshagent-public/images/python-sdk:{SERVER_VERSION}-esgz"
  command: python /src/mcp_chatbot/mcp_chatbot.py
  storage:
    images:
      # Replace this image tag with your own code-only image if you build one.
      - image: "us-central1-docker.pkg.dev/meshagent-public/images/python-docs-examples:{SERVER_VERSION}"
        path: /src
        read_only: true
How the paths work:
  • Your code image contains /mcp_chatbot/mcp_chatbot.py
  • It’s mounted at /src in the runtime container
  • The command runs python /src/mcp_chatbot/mcp_chatbot.py
Note: The default YAML in the docs uses us-central1-docker.pkg.dev/meshagent-public/images/python-docs-examples so you can test this example immediately without building your own image first. Replace this with your actual image tag when deploying your own code.
Step 3c: Deploy the agent Next from the CLI in the directory where your meshagent.yaml file is run: 
meshagent service create --file "meshagent.yaml" --room=quickstart
The MCP ChatBot is now deployed to the quickstart room! Now the agent will always be available inside the room for us to chat with. You can interact with the agent directly from the Studio or from Powerboards.

​
Step 4: Use Your Deployed Agent

Next open MeshAgent Studio, go to a room where the service is deployed, and begin talking to the ChatBot.

​
Security and best practices

When adding external tools like MCP Servers or OpenAI Connectors consider:
  • What data you’re sharing with external services
  • Who operates the MCP servers you connect to
  • Whether agents should require approval before using certain tools