add-agents-mcp-server
Add an MCP (Model Context Protocol) server to a Mattermost plugin so the Agents plugin can call its tools. Use when implementing cross-plugin MCP, exposing AI tools from a Mattermost plugin to the Age
SKILL.mdplugins/plugin-development/skills/add-agents-mcp-server/SKILL.md
GitHubAdd Agents MCP Server
Add a cross-plugin MCP (Model Context Protocol) server to a Mattermost plugin so the Mattermost Agents plugin can discover and call its tools. Uses the github.com/mattermost/mattermost-plugin-agents/external/pluginmcp helper, which handles tool-name namespacing, inter-plugin auth, user-ID propagation, and async registration retries.
When to use this skill
Use this skill when a developer wants their Mattermost plugin to expose tools (look up records, query state, create artifacts) that the Agents plugin's LLM agents can call on the user's behalf. The reference implementation lives at mattermost/mattermost-plugin-demo (server/mcp.go, server/mcp_tools.go).
Prerequisites
Before starting, confirm these against the target plugin:
- Mattermost server: 11.3 or newer (the helper uses
Plugin.PluginHTTPStream). - Go: 1.26+ (matches the demo plugin's
go 1.26.2). - Plugin server code lives in
server/and usesgithub.com/mattermost/mattermost/server/public/plugin(the standard Mattermost plugin layout). If the plugin is webapp-only or uses a non-standard server layout, this skill does not apply. plugin.jsonhas a stableidthat is reverse-DNS style (e.g.com.example.plugin-foo) and does not contain__. Double-underscore is the namespace separator on the Agents side and a plugin ID containing__parses ambiguously.
No plugin.json changes are required — MCP integration is entirely server-side.
Instructions
Phase 0: Prepare the branch
- Ensure the working tree is clean.
- Switch to the default branch (
masterormain) and pull. - Create a feature branch:
git switch -c add-mcp-server.
Phase 1: Add dependencies
Edit server/go.mod (or the repo's go.mod if there is no separate server module) to add:
require (
github.com/mattermost/mattermost-plugin-agents v0.0.0-<commit-from-master>
github.com/modelcontextprotocol/go-sdk v1.4.1
)
Then run go mod tidy from the directory that owns go.mod.
If a tagged release of mattermost-plugin-agents that exports external/pluginmcp/ is not yet available, ask the user whether to use a replace directive against a local checkout:
replace github.com/mattermost/mattermost-plugin-agents => ../mattermost-plugin-agents
Phase 2: Add MCP server fields to the Plugin struct
Find the file declaring the Plugin struct (typically server/plugin.go). Add a thread-safe holder for the MCP server:
import (
"sync"
"github.com/mattermost/mattermost-plugin-agents/external/pluginmcp"
)
type Plugin struct {
plugin.MattermostPlugin
// ... existing fields ...
mcpServerLock sync.RWMutex
mcpServer *pluginmcp.Server
}
The lock guards lazy initialization in OnActivate and concurrent reads from ServeHTTP.
Phase 3: Create server/mcp.go
This file owns the MCP server lifecycle. Use indirected var function references (mcpNewServer, mcpRegister, mcpUnregister) so tests can override them — this matches the demo plugin's pattern.
package main
import (
"errors"
"net/http"
"strings"
"github.com/mattermost/mattermost-plugin-agents/external/pluginmcp"
)
const mcpBasePath = "/mcp"
var (
mcpNewServer = pluginmcp.NewServer
mcpRegister = func(server *pluginmcp.Server) error {
return server.Register()
}
mcpUnregister = func(server *pluginmcp.Server) error {
return server.Unregister()
}
)
func (p *Plugin) ensureMCPServer() error {
p.mcpServerLock.Lock()
defer p.mcpServerLock.Unlock()
if p.mcpServer != nil {
return nil
}
if manifest.Id == "" {
return errors.New("plugin manifest id is required for MCP server")
}
if manifest.Version == "" {
return errors.New("plugin manifest version is required for MCP server")
}
serverName := strings.TrimSpace(manifest.Name)
if serverName == "" {
return errors.New("plugin manifest name is required for MCP server")
}
server := mcpNewServer(p.API, pluginmcp.Config{
PluginID: manifest.Id,
Name: serverName + " MCP",
Path: mcpBasePath,
ExposeExternal: false, // Defaults false. Directive: Ask the user whether they want this MCP server exposed externally or not - false is the default for security reasons.
Version: manifest.Version,
})
p.registerMCPTools(server)
p.mcpServer = server
return nil
}
func (p *Plugin) registerMCPServerBestEffort() {
server := p.currentMCPServer()
if server == nil {
p.API.LogWarn("MCP registration unavailable; continuing plugin activation", "reason", "server not initialized")
return
}
if err := mcpRegister(server); err != nil {
p.API.LogWarn("MCP registration unavailable; continuing plugin activation", "err", err.Error())
}
}
func (p *Plugin) unregisterMCPServerBestEffort() {
server := p.currentMCPServer()
if server == nil {
return
}
if err := mcpUnregister(server); err != nil {
p.API.LogWarn("MCP unregister failed; continuing plugin shutdown", "err", err.Error())
}
}
func (p *Plugin) serveMCPIfMatch(w http.ResponseWriter, r *http.Request) bool {
if r.URL.Path != mcpBasePath && !strings.HasPrefix(r.URL.Path, mcpBasePath+"/") {
return false
}
server := p.currentMCPServer()
if server == nil {
http.NotFound(w, r)
return true
}
server.ServeHTTP(w, r)
return true
}
func (p *Plugin) currentMCPServer() *pluginmcp.Server {
p.mcpServerLock.RLock()
defer p.mcpServerLock.RUnlock()
return p.mcpServer
}
Register() returns immediately and retries asynchronously (1s → 2s → 4s → 8s, up to 15 attempts) until the Agents plugin acknowledges, so plugin activation is not blocked when the Agents plugin is not yet up.
Phase 4: Create server/mcp_tools.go
Define typed input/output structs and register each tool with pluginmcp.AddTool. Tool names are prefixed with {pluginID}__ automatically — the LLM sees com_example_plugin_foo__echo, but you write echo.
package main
import (
"context"
"fmt"
"github.com/mattermost/mattermost-plugin-agents/external/pluginmcp"
"github.com/mattermost/mattermost/server/public/model"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
type EchoArgs struct {
Message string `json:"message" jsonschema:"The string to echo back,minLength=1"`
}
type EchoOutput struct {
Echoed string `json:"echoed" jsonschema:"The same string that was passed in"`
}
type GetUserDisplayNameArgs struct{}
type GetUserDisplayNameOutput struct {
UserID string `json:"user_id" jsonschema:"Mattermost user ID of the caller"`
Username string `json:"username" jsonschema:"Username of the caller"`
DisplayName string `json:"display_name" jsonschema:"Full-name display name of the caller, falling back to username"`
}
func (p *Plugin) registerMCPTools(server *pluginmcp.Server) {
pluginmcp.AddTool(server, &mcp.Tool{
Name: "echo",
Description: "Echo a string back to the caller. Useful for verifying the MCP round-trip.",
}, p.echoHandler)
pluginmcp.AddTool(server, &mcp.Tool{
Name: "get_user_display_name",
Description: "Look up the calling user's display name.",
}, p.getUserDisplayNameHandler)
}
func (p *Plugin) echoHandler(_ context.Context, _ *mcp.CallToolRequest, in EchoArgs) (*mcp.CallToolResult, EchoOutput, error) {
return nil, EchoOutput{Echoed: in.Message}, nil
}
func (p *Plugin) getUserDisplayNameHandler(ctx context.Context, _ *mcp.CallToolRequest, _ GetUserDisplayNameArgs) (*mcp.CallToolResult, GetUserDisplayNameOutput, error) {
userID := pluginmcp.GetUserID(ctx)
if userID == "" {
return nil, GetUserDisplayNameOutput{}, fmt.Errorf("no Mattermost user ID in tool context (did the request arrive via pluginmcp.ServeHTTP?)")
}
user, err := p.client.User.Get(userID)
if err != nil {
return nil, GetUserDisplayNameOutput{}, fmt.Errorf("failed to fetch user %s: %w", userID, err)
}
return nil, GetUserDisplayNameOutput{
UserID: user.Id,
Username: user.Username,
DisplayName: user.GetDisplayName(model.ShowFullName),
}, nil
}
Handler signature is the go-sdk's mcp.ToolHandlerFor[In, Out]:
func(context.Context, *mcp.CallToolRequest, In) (*mcp.CallToolResult, Out, error)
Return (nil, out, nil) and the helper packs out into a CallToolResult. Return a non-nil *mcp.CallToolResult to fully control the response (multi-content replies, IsError, etc.).
Replace the demo tools above with tools meaningful to the target plugin. Aim for about 10 tools maximum with union-typed args, not many narrow tools — every tool costs schema tokens in every LLM request.
Phase 5: Wire into OnActivate / OnDeactivate
In the file with OnActivate (typically server/activate_hooks.go or server/plugin.go):
func (p *Plugin) OnActivate() error {
// ... existing activation logic ...
if err := p.ensureMCPServer(); err != nil {
return errors.Wrap(err, "failed to initialize MCP server")
}
p.registerMCPServerBestEffort()
return nil
}
func (p *Plugin) OnDeactivate() error {
// ... existing deactivation logic ...
p.unregisterMCPServerBestEffort()
return nil
}
Order matters:
ensureMCPServermust run afterp.client = pluginapi.NewClient(...)and any other initialization tool handlers depend on.registerMCPServerBestEffortmust run afterensureMCPServer.Register()errors are logged and swallowed so a temporarily-down Agents plugin does not block activation.unregisterMCPServerBestEffortshould run regardless of whether the rest of deactivation succeeded.
Phase 6: Route MCP requests in ServeHTTP
Find the plugin's ServeHTTP method (typically server/http_hooks.go or server/plugin.go). Match the MCP path before falling through to the regular router:
func (p *Plugin) ServeHTTP(c *plugin.Context, w http.ResponseWriter, r *http.Request) {
if p.serveMCPIfMatch(w, r) {
return
}
p.router.ServeHTTP(w, r)
}
Do not add an additional auth gate around serveMCPIfMatch — pluginmcp.Server.ServeHTTP already rejects requests that lack Mattermost-Plugin-ID: mattermost-ai (a header Mattermost strips on external requests, so only inter-plugin RPC sees it).
Phase 7: Add a smoke test (recommended)
Create server/mcp_tools_test.go mirroring the demo plugin. The test wires ServeHTTP into a httptest.Server, sets Mattermost-Plugin-ID: mattermost-ai, and uses the go-sdk client to call ListTools / CallTool. See mattermost-plugin-demo/server/mcp_tools_test.go (branch IDEA-006-cross-plugin-mcp) for a full example.
Key test setup:
const agentsPluginID = "mattermost-ai"
req.Header.Set("Mattermost-Plugin-ID", agentsPluginID)
req.Header.Set("X-Mattermost-UserID", "test-user-id") // only if testing user-context tools
Phase 8: Verify
make(ormake dist) to confirm the plugin builds.make testto run unit tests.make check-styleto ensure no linter regressions.- Manual end-to-end test:
- Install the Agents plugin (master/main branch with cross-plugin MCP support, see references).
- Install this plugin.
- In the Agents system console, open the Tools tab. The plugin's tools should appear as
{sanitized-plugin-id}__{tool-name}, with per-tool policy controls. - Trigger a chat with an agent and exercise a tool.
- Tail server logs for
Connected to plugin MCP server <pluginID>from the Agents plugin — its absence meansRegister()never succeeded.
Configuration reference
type Config struct {
PluginID string // required; must equal plugin.json "id"
Name string // human-readable; shown in admin UI
Path string // your plugin's MCP endpoint, e.g. "/mcp"
ExposeExternal bool // if true, tools may appear on Agents' external MCP aggregate
// (still subject to admin Enabled toggle and per-tool policy)
Version string // optional; defaults to "0.0.1"
}
API reference
pluginmcp.NewServer(api, cfg) *Server—p.APIsatisfies thePluginAPIinterface.pluginmcp.AddTool[In, Out](s, tool, handler)— free function, not a method, because Go disallows type parameters on methods.(*Server).ServeHTTP(w, r)—http.Handler; route to it from yourServeHTTPfor requests undercfg.Path.(*Server).Register() error— start async registration; returns immediately, retries in a goroutine.(*Server).Unregister() error— synchronously cancels pending retries and POSTs one unregister.pluginmcp.GetUserID(ctx) string— returns the user ID stashed byServeHTTP, or""if absent.
Constraints and gotchas
- Tool-name sanitization.
AddToolprepends{sanitizedPluginID}__totool.Name, replacing any character outside[A-Za-z0-9_-]with_to satisfy Bifrost / Anthropic's^[a-zA-Z0-9_-]{1,128}$. Iftool.Namealready starts with the prefix, it is not duplicated. PluginIDmust not contain__. Use a normal reverse-DNS ID likecom.example.plugin-foo.GetUserIDis trustworthy only inside a request that came throughpluginmcp.Server.ServeHTTP. External callers can't inject one. Don't readX-Mattermost-UserIDdirectly from headers; always go throughGetUserID.- Don't double-gate auth. Adding your own plugin-ID check around
serveMCPIfMatchis redundant and will likely break the helper's own check. - Registration is one-shot per
OnActivate. If the Agents plugin restarts later, the in-memory registration is lost on the Agents side. Admin-persisted entries are restored on Agents-plugin restart, but a never-saved registration only comes back when your plugin re-activates. Permanent (non-retriable) errors logregistration with Agents plugin failed permanentlyand stop. - Tool budget. Each tool costs ~20–200 schema tokens in every LLM request. Aim for ~10 tools per plugin, with union-typed args, over many narrow tools.
ExposeExternalvs adminEnabled. Each register POST sendsexpose_externalfrom yourConfig. Admins still control the server'sEnabledstate and per-tool policy in the Agents system console; those settings are preserved across re-registration.
Troubleshooting
- Tool doesn't appear in the admin Tools tab. Look for
Connected to plugin MCP server <pluginID>in the Agents-plugin log; absence indicatesRegister()was never called or kept failing. The retry loop logsregistration with Agents plugin gave up after N attemptson terminal failure andfailed permanentlyon a non-retriable 4xx. GetUserIDreturns"". Either the request didn't go throughpluginmcp.Server.ServeHTTP(typical in unit tests — inject a context yourself), or your outerServeHTTPisn't routing to it (checkmcpBasePathmatches yourConfig.Path).- Registration keeps retrying. Common causes: Agents plugin disabled, in a crash loop, or
cfg.PluginIDdoesn't matchplugin.json'sid(the Agents plugin returns 403, which is non-retriable). - 403 from
serveMCPIfMatchduring local curl. Expected — Mattermost stripsMattermost-Plugin-IDon external requests. Test cross-plugin calls through the Agents plugin or a unit test that sets the header explicitly.
References
- Helper package and reference docs:
mattermost-plugin-agents/external/pluginmcp/(README.md,pluginmcp.go,server.go,tools.go,context.go,registration.go). - Reference plugin implementation:
mattermost-plugin-demobranchIDEA-006-cross-plugin-mcp— seeserver/mcp.go,server/mcp_tools.go,server/activate_hooks.go,server/http_hooks.go, andserver/mcp_tools_test.go. - MCP Go SDK: https://github.com/modelcontextprotocol/go-sdk.