MCP Toolsets Tutorial

Integrate external MCP servers into your agents.

This tutorial shows how to integrate external MCP (Model Context Protocol) servers into your Goa-AI agents.

What You’ll Build

An agent that consumes tools from an external MCP server, demonstrating:

  • MCP server declaration
  • Agent integration
  • Runtime wiring
  • Tool execution

Prerequisites

Step 1: Declare MCP Server

In your service design, declare the MCP server:

package design

import (
    . "goa.design/goa/v3/dsl"
    . "goa.design/goa-ai/dsl"
)

var _ = Service("assistant", func() {
    Description("MCP server for assistant tools")
    
    // MCP server declaration
    // ... MCP DSL here ...
})

Step 2: Reference MCP Suite in Agent

var AssistantSuite = MCPToolset("assistant", "assistant-mcp")

var _ = Service("orchestrator", func() {
    Agent("chat", "Conversational runner", func() {
        Use(AssistantSuite)
    })
})

Step 3: Wire MCP Caller at Runtime

import (
    "goa.design/goa-ai/features/mcp"
    mcpassistant "example.com/assistant/gen/assistant/mcp_assistant"
)

caller := featuresmcp.NewHTTPCaller("https://assistant.example.com/mcp")

if err := mcpassistant.RegisterAssistantAssistantMcpToolset(ctx, rt, caller); err != nil {
    log.Fatal(err)
}

Step 4: Use MCP Tools

Your planner can now reference MCP tools just like native toolsets:

func (p *MyPlanner) PlanStart(ctx context.Context, in *planner.PlanInput) (*planner.PlanResult, error) {
    return &planner.PlanResult{
        ToolCalls: []planner.ToolRequest{
            {
                Name:    "assistant.assistant-mcp.some_tool",
                Payload: []byte(`{"param": "value"}`),
            },
        },
    }, nil
}

Next Steps