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.
For a concrete MCP walkthrough, see Supabase MCP.

​
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 How Tools and Toolkits Work.

​
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 a process-backed agent with a chat channel and 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. A process-backed agent with a chat channel does this automatically with the --mcp flag. 
meshagent process join --room=quickstart --agent-name=agent --channel chat --mcp
Note: The process CLI 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.

​
Step 4: Test in MeshAgent Studio

Go to MeshAgent Studio and try out the agent. 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 a process-backed agent with MCP enabled

meshagent process join --room=quickstart --agent-name=agent --channel chat --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 process

If the agent should always have MCP tools available on every turn, enable required MCP instead of making the tools user-toggleable. Once the MCP or connector service is deployed, start the agent with --require-mcp: 
meshagent process join \
  --room=quickstart \
  --agent-name=agent \
  --channel chat \
  --require-mcp
You can use the same pattern when deploying: 
meshagent process deploy \
  --room=quickstart \
  --service-name=agent \
  --agent-name=agent \
  --channel chat \
  --require-mcp
Use this approach when:
  • the agent should always have MCP tools available
  • users should not toggle the tool on and off per message
  • you want a stable tool configuration for every turn

​
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