MCP Tools

MCP (Model Context Protocol) tools allow your agent to connect to external MCP servers and use their tools. This enables your agent to interact with various services and resources through standardized MCP tool interfaces.

Connecting to an MCP Server

To use MCP tools, you first need to create an MCP client using the mcpclient.NewClient function.:

import (
    "context"
    "github.com/hastekit/agent-sdk-go/pkg/agents/mcpclient"
)

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
    mcpclient.WithTransport("sse"),
)
if err != nil {
    log.Fatal(err)
}

Parameters

ctx: The context for the connection
endpoint: The SSE endpoint URL of the MCP server (e.g., "http://localhost:9001/sse")

Custom Headers

You can also configure the MCP Client to send custom HTTP headers while interacting with the MCP server.

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
    mcpclient.WithTransport("sse"),
	mcpclient.WithHeaders(map[string]string{
        "token": "your-token",
    }),
)

Filtering Tools

You can optionally restrict which tools are exposed to the agent using the WithToolFilter(...) option. Only the named tools are surfaced; all others are dropped.

// Only use specific tools
mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
    mcpclient.WithTransport("sse"),
		mcpclient.WithToolFilter("list_users"),
	)

Deferred (Lazy-Loaded) Tools

Use WithDeferredTools(...) to mark tools as deferred. Deferred tools are not added to the LLM’s tool list upfront; instead they are discovered and activated on demand via the ToolSearch meta-tool. This keeps the prompt small when an MCP server exposes a large number of tools.

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
    mcpclient.WithTransport("sse"),
    mcpclient.WithDeferredTools("rarely_used_tool"),
)

Pass "*" to defer every tool the server exposes, which saves keeping a list in sync with a server whose catalog changes:

mcpclient.WithDeferredTools("*")

See Deferred Tools for how the activation flow works and when to defer a tool.

Schema Caching

By default, the client connects to the MCP server to fetch tool schemas on every ListTools call. You can cache schemas to avoid repeated round-trips:

WithCacheTTL(ttl time.Duration) sets how long cached schemas remain valid.
WithSchemaCache(cache SchemaCache) injects a SchemaCache implementation. When set, ListTools() checks the cache before connecting to the MCP server. Back it with Redis (or a similar shared store) to share cached schemas across multiple pods.

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
    mcpclient.WithTransport("sse"),
		mcpclient.WithCacheTTL(5*time.Minute),
		mcpclient.WithSchemaCache(myRedisSchemaCache),
	)

Approval-Required Tools

Use WithApprovalRequiredTools(...) to mark specific MCP tools as requiring human approval before they run. See the Human in the Loop page for the full approval flow.

Transport

You can set the transport to be used for the connection. Supported transports are SSE and Streamable HTTP. If not specified it defaults to SSE

mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
		mcpclient.WithTransport("streamable-http"), // or "sse"
	)

On streamable-http, the client also opens the post-init server→client SSE stream. Some servers don’t support that standalone GET stream, and the client then hangs waiting on a stream that never opens. Turn it off for those servers:

mcpclient.WithDisableStandaloneSSE(true) // no effect on the "sse" transport

Tool Annotations

MCP tools carry whatever behavioural hints their server declared — read-only, destructive, idempotent, open-world — and the SDK converts them into the same agents.ToolAnnotations shape a local function tool uses. Nothing extra is needed to pick them up, and one permission policy can read both:

a := agents.AnnotationsOf(tool)
if a.IsDestructive() {
    // gate it — see Hooks
}

The MCP wire format carries readOnlyHint and idempotentHint as bare booleans, so an absent hint arrives as false — which is the spec’s default for both. destructiveHint and openWorldHint stay unset when the server said nothing, leaving the conservative defaults (destructive, open world) to the Is* helpers. See Tool Annotations for the full table and how to declare them on your own tools.

Hints are self-reported. Never let a hint from an untrusted MCP server widen what a tool is allowed to do.

Progress Notifications

When a tool call is streaming, the client attaches a progress token so the server can send notifications/progress for the duration of that call. Those notifications arrive on the run’s chunk stream as tool.progress chunks, exactly like progress emitted by a function tool:

for chunk := range handle.Chunks {
    if chunk.OfToolProgress != nil {
        p := chunk.OfToolProgress
        fmt.Printf("%s: %.0f/%.0f %s\n", p.ToolName, p.Progress, p.Total, p.Message)
    }
}

CallID ties each update back to the in-flight call. Total is optional — 0 means unknown. Progress is a live side stream: under the durable runtimes it is published directly rather than journaled, so it is never replayed.

Elicitation

An MCP server can ask the user for something mid-call rather than answering: a form to fill in, or a URL to visit. The SDK maps that onto the same pause the agent already uses for human-in-the-loop approvals — the run ends with an interrupt, and the answer arrives on a later request. The pause is surfaced as an Interrupt whose Mode says what is being asked:

Mode	Meaning
`responses.InterruptModeApproval`	A human approve/reject gate on a tool call
`responses.InterruptModeForm`	The user fills a form described by a JSON schema
`responses.InterruptModeURL`	The user must visit a URL (e.g. an OAuth connect flow) before the tool can proceed

type Interrupt struct {
    FunctionCallMessage responses.FunctionCallMessage `json:"function_call_message"`
    Mode                responses.InterruptMode       `json:"mode"`
    Elicitations        []mcp.ElicitParams            `json:"elicitations,omitempty"`
    IsNested            bool                          `json:"is_nested,omitempty"`
}

For form and URL modes, Elicitations carries the server’s own request — its message, and for a form the RequestedSchema describing the fields to collect.

Answering a form

Resume the same way as an approval, but attach the filled form as the resolution’s Content. It must match the RequestedSchema the pause advertised:

filled, _ := sonic.Marshal(map[string]any{
    "email":     "alice@example.com",
    "team_size": 12,
})

resolution := responses.InputMessageUnion{
    OfFunctionCallInterruptResolution: &responses.FunctionCallInterruptResolutionMessage{
        ID: uuid.NewString(),
        Resolutions: []responses.InterruptResolution{
            {
                CallID:  out.Interrupts[0].FunctionCallMessage.CallID,
                Action:  responses.InterruptActionApprove,
                Content: filled,
            },
        },
    },
}

handle, err := agent.Execute(ctx, &agents.AgentInput{
    Namespace:     "default",
    ThreadID:      threadID,
    PreviousRunID: out.RunID,
    Message: history.Message{
        Messages: []responses.InputMessageUnion{resolution},
    },
})

An approval carrying content becomes an MCP accept; a rejection becomes a decline, and its content is dropped rather than delivered — a rejected form has no answer to pass on.

The request id and the server’s own opaque state are carried across the pause in thread state, so the resuming call answers the server’s original question rather than provoking a fresh one. That is what lets a server resume from where it left off instead of redoing the work that preceded the question.

Only one input request per call is supported: one interrupt carries one answer, so a second question in the same call would have nowhere to put its reply.

Complete Example

Here’s a complete example of an agent using MCP tools:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

	"github.com/bytedance/sonic"
	"github.com/hastekit/agent-sdk-go/pkg/agents"
	"github.com/hastekit/agent-sdk-go/pkg/agents/history"
	"github.com/hastekit/agent-sdk-go/pkg/agents/mcpclient"
	"github.com/hastekit/agent-sdk-go/pkg/gateway/llm/responses"
	hastekit "github.com/hastekit/agent-sdk-go"
)

func main() {
    // Initialize LLM client
    client := hastekit.NewLLMClient([]hastekit.ProviderConfig{
        {
            ProviderName: hastekit.ProviderOpenAI,
            ApiKeys: []*hastekit.APIKeyConfig{
                {
                    Name:   "Key 1",
                    APIKey: os.Getenv("OPENAI_API_KEY"),
                },
            },
        },
    })

    // Bind a model
    model := client.Model("OpenAI/gpt-4o-mini")

    // Create conversation history
    conv := hastekit.NewFileHistory("./conversations")

    // Connect to MCP server
    mcpClient, err := mcpclient.NewClient(context.Background(), "http://localhost:9001/sse",
		mcpclient.WithHeaders(map[string]string{
			"token": "your-token",
		}),
		mcpclient.WithToolFilter("list_users"),
	)

    // Create agent with MCP tools
    agent := hastekit.NewAgent(&hastekit.AgentConfig{
        Name:        "Hello world agent",
        Instruction: hastekit.NewPrompt("You are helpful assistant."),
        LLM:         model,
        History:     conv,
        McpServers:  []agents.MCPToolset{mcpClient},
    })

    // Execute agent
    handle, err := agent.Execute(context.Background(), &agents.AgentInput{
        Message: history.Message{
            Messages: []responses.InputMessageUnion{
                responses.UserMessage("Hello!"),
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    out, err := handle.Result()
    if err != nil {
        log.Fatal(err)
    }

    b, _ := sonic.Marshal(out)
    fmt.Println(string(b))
}

Getting started

LLM Gateway

Agents

Workflows

Connecting to an MCP Server

Parameters

Custom Headers

Filtering Tools

Deferred (Lazy-Loaded) Tools

Schema Caching

Approval-Required Tools

Transport

Tool Annotations

Progress Notifications

Elicitation

Answering a form

Complete Example

​Connecting to an MCP Server

​Parameters

​Custom Headers

​Filtering Tools

​Deferred (Lazy-Loaded) Tools

​Schema Caching

​Approval-Required Tools

​Transport

​Tool Annotations

​Progress Notifications

​Elicitation

​Answering a form

​Complete Example

Connecting to an MCP Server

Parameters

Custom Headers

Filtering Tools

Deferred (Lazy-Loaded) Tools

Schema Caching

Approval-Required Tools

Transport

Tool Annotations

Progress Notifications

Elicitation

Answering a form

Complete Example