AgentCat v2.1.0 — sturdier session handles: IDs issued first, structured mcp_session status

AgentCat v2.1.0 makes explicit session handles sturdier and easier for agents to consume — for both Go MCP libraries. There are no Go API changes for adapter users; the delta is in the wire contract between your server and the agent.

Why

Session handles are easy for callers to miss when they arrive at the tail of a long result: clients that truncate large tool outputs drop the issuance notice entirely, and agents then start new sessions instead of continuing the one they were given. And a handle that is optional in the schema is one an agent can simply forget, silently splitting one task into several sessions.

What's new

IDs are issued at the start of the response

The text block announcing a newly issued session_id is now the first content element of the result instead of the last, so it survives client-side truncation of long results. Published events are unaffected: they still carry your original, undecorated response.

session_id is required, with an explicit value contract

session_id now appears in each tool's required list with a machine-checked pattern, ^(start|ses_[0-9A-Za-z]{27})$: an agent sends the literal start to begin a new task, or the ses_ ID issued for the task underway. Every call states its session explicitly, so sessions never split by accident.

Calls that omit the parameter are still accepted and treated exactly like start, so requiredness is enforced only by schema-aware clients. On mcp-go, the declaration AgentCat writes onto your registered schema keeps the injected parameters optional, so WithInputSchemaValidation never rejects a call for omitting one (pinned by TestRegisteredInputDeclarationKeepsCustomerContract).

mcp_session replaces _mcp_instructions

The structured mirror in structuredContent — declared on each extended output schema — is now mcp_session: {session_id?, agent_id?, status?}. A machine-readable status enum (issued / active / unrecognized) replaces the prose instructions member, so every response state an agent can encounter is pre-announced in the schema. Hook-mode (ResolveSessionID) and foreign resolutions carry agent_id alone.

Recovery is explicit

An unrecognized value is reported both as mcp_session.status: "unrecognized" and as a leading [session_id unrecognized …] text block, with the recovery path — re-send the ID issued earlier, or start if none was — stated in the schema. As before, no replacement is issued in that response: if a value arrived at all, the agent already has a good one.

Leaner, self-describing copy

The session_id and agent_id descriptions explain the mechanism in terms of what this server does and pre-announce both text-block headers, so responses always match the schema's stated contract. The two agent_id description variants collapse into one, used in both modes. Copy stays byte-identical across AgentCat SDKs and pinned by golden tests; the same strings and wire shape are landing in the TypeScript and Python SDKs.

Breaking wire changes

Only for consumers that assert on response internals or advertised schemas — tests, proxies, clients that read structuredContent:

• The structuredContent mirror key is renamed _mcp_instructions → mcp_session; its instructions member is removed in favor of status.
• The issuance text block moved from the last to the first content position, and its headers changed: [session_id issued — see this tool's session_id parameter description] / [session_id unrecognized — see this tool's session_id parameter description].
• session_id now appears in each tool's required array alongside context (and agent_id where injected), and declares the validation pattern above.
• Root module only: agentcat.MCPInstructionsKey is renamed agentcat.MCPSessionKey. Adapter users never touch it.

Everything else — argument stripping, handle validation, the agentcat_session_id_source tags, hook mode, redaction, exporters, Options — is unchanged. Details in the migration guide.

Also in this release

• A regression test pins that event metadata (ServerName, ClientVersion, Tags, Properties, …) never reaches RedactSensitiveInformation — only Parameters, Response, UserIntent, and Error are walked (#8).
• Dependabot now delivers security updates only, with no automated merges (#7, #12).

Compatibility

	mark3labs/mcp-go	modelcontextprotocol/go-sdk
Supported versions	v0.53.0 – v0.57.0	v1.4.1 – v1.7.0
Installs with	v0.57.0	v1.7.0
Stateless 2026-07-28 transports	✅	✅
stdio / streamable HTTP	✅	✅
Per-request server factories	✅	✅
MRTR tagging	— (not in mcp-go)	v1.7.0+
Go	1.25+	1.25+

Unchanged from v2.0.0: every version in both ranges is tested with -race on each push.

Install

go get go.agentcat.com/sdk/mcpgo/v2@v2.1.0        # mark3labs/mcp-go
go get go.agentcat.com/sdk/officialsdk/v2@v2.1.0  # official modelcontextprotocol/go-sdk

Submodules are tagged alongside the root: mcpgo/v2.1.0, officialsdk/v2.1.0.

Full changelog: v2.0.0...v2.1.0

AgentCat v2.0.0 — explicit handles for sessionless MCP, for both Go MCP libraries

AgentCat v2 rebuilds task correlation for the sessionless MCP era — for both Go MCP libraries.

Why v2

The MCP 2026-07-28 specification removed protocol-level sessions. SEP-2567 eliminated the initialize handshake and the Mcp-Session-Id header — every request is now self-contained. Sessions were the built-in thread tying related tool calls together; without them, a stateless deployment sees each call in isolation.

The MCP core team's guidance for cross-call state is explicit: mint an explicit handle from a tool and have the model pass it back as an argument. AgentCat v2 rebuilds correlation on exactly this pattern. Track() mints an explicit session_id handle and delivers it to the agent, which threads it back on every subsequent call — correlation that holds across stateless HTTP, load balancers, and per-request server instances, where transport-session inference gives you nothing at all.

What it costs you: session_id adds 323 tokens to a tool's schema — 0.03% of a 1M-token context window. The injected copy is byte-identical across every AgentCat SDK and pinned by a golden test, so the number is the same wherever you integrate. Tokens scale with the tools loaded into a given request, not with the size of your catalog.

What's new

Task correlation via explicit handles

• session_id is injected into each tracked tool's input schema. Agents echo it back on every call, grouping related calls into one task — even across stateless HTTP, load-balanced deployments, and per-request server instances.
• Issued IDs are delivered via a trailing [MCP INSTRUCTIONS] text block and, for tools declaring an output schema, mirrored into structuredContent as _mcp_instructions, so clients that only read structured results still receive them.
• Injected parameters are stripped before your handler runs — your tool code never sees them — and mint-back instructions never appear in published events: every event carries your raw request and your original, undecorated response.
• Session IDs land in the same sessionId event field with the same ses_ prefix, so your existing dashboards, queries, and exporter pipelines keep working untouched.
• Already track your own correlation IDs? Set ResolveSessionID and AgentCat derives its session deterministically from your identifier — the same input produces the same session across processes and languages — and injects no session_id parameter at all.

Handles are validated

• AgentCat trusts only a session_id it issued — the ses_ prefix plus a 27-character KSUID. Event.SessionId is exempt from both redaction hooks, so a value adopted there could never be scrubbed afterwards; anything AgentCat did not mint is never adopted.
• A handle this server did not mint publishes without a session, and the agent is told to re-send the ID it was given rather than handed a new one.
• A tool that declares its own session_id is never read from: your parameter reaches your handler untouched, those calls publish sessionless, and you get one actionable error per tool naming the fix.
• Every event carries an agentcat_session_id_source tag: minted, supplied, hook, invalid, or foreign.

Agent attribution (opt-in)

• agent_id — enable with EnableAgentTracking: true. Each agent self-generates a model|harness|nonce ID, so parallel agents collaborating on one task stay individually attributable. Off by default; no server-side minting.

Both Go MCP libraries

• One feature set behind identical Options on both adapters: go.agentcat.com/sdk/mcpgo/v2 for mark3labs/mcp-go and go.agentcat.com/sdk/officialsdk/v2 for modelcontextprotocol/go-sdk. You import only the adapter matching your library.
• Per-request serving is first-class: call Track() inside your server factory. Queues, exporters, and diagnostics initialize once and are shared across instances; per-server state is released when the server object is garbage collected.
• mcp-go strict validation is supported: AgentCat declares its parameters on your registered tool schemas as optional properties only — your required list and your additionalProperties setting are never changed — so servers using WithInputSchemaValidation, WithStrictInputSchemaDefault, or WithOutputSchemaValidation accept exactly the calls AgentCat's advertised schemas invite.
• get_more_tools is annotated read-only via MCP tool annotations.

Fault containment

An adversarial audit of every failure path between AgentCat and the host server hardened v2 around one guarantee: an AgentCat failure never takes your server down with it. Each fix landed with a regression test that fails on the commit before it.

• officialsdk no longer round-trips your arguments through float64 when stripping injected parameters: every surviving literal re-marshals verbatim, so integers above 2^53 reach your handler — and your published events — exactly as sent.
• Per-request factory topologies no longer leak: neither adapter holds a strong reference from AgentCat's process-lifetime state back to your server, so every per-request server instance is released when it dies. This includes a customer-owned *server.Hooks value shared across mcp-go servers — it is instrumented exactly once, with closures that resolve the live server from the request context instead of capturing it.
• Injection is best-effort and never fails a tools/list: a tool that already declares a parameter keeps its own, and composed (oneOf/allOf/anyOf), unreadable, or absent input schemas are advertised untouched.
• Every customer callback — Identify, EventTags, EventProperties, RedactEvent, RedactSensitiveInformation, ResolveSessionID — is panic-guarded; a failure costs that call's analytics, never the call.
• When the log file can't be created (containers without a resolvable home directory), logging goes silent instead of falling back to stdout — on stdio transports, stdout is the JSON-RPC wire.

Known limitations, accepted for 2.0.0 and tracked for a follow-up: the event queue is bounded by count (10,000) but not bytes, and events are truncated after dequeue, so a long AgentCat API outage combined with very large tool results can hold significant memory; and debug-log writes are synchronous, so with Debug enabled an unresponsive network-mounted home directory would stall the process.

Reliability

• Real-transport e2e suites over stdio and streamable HTTP for both adapters, plus a per-request factory topology lane.
• Every version in both supported MCP-library ranges is tested with -race on each push by dedicated compatibility workflows.

Breaking changes

• Transport-session machinery, identity caches, and identify events are removed. Correlation now flows through explicit session_id handles.
• Module paths move to /v2: go.agentcat.com/sdk/v2, go.agentcat.com/sdk/mcpgo/v2, go.agentcat.com/sdk/officialsdk/v2. v1 paths keep resolving untouched, so you can adopt v2 one service at a time.
• v2 publishes only two event types — mcp:tools/call and agentcat:custom. mcp:initialize, mcp:tools/list, agentcat:identify, and all resource/prompt events are gone.
• Identify now runs on every tool call and stamps only that call's event. There is no identity cache — keep the hook cheap.
• Agent tracking is opt-in — EnableAgentTracking defaults to false.
• PublishCustomEvent takes verbatim session IDs; CustomEventData.SessionID replaces session references.
• A hand-written session_id no longer correlates, and tools with composed, opaque, or malformed input schemas now publish sessionless.

For most integrations the upgrade is the /v2 import path and go mod tidy — code changes only where a removed API was used. The migration guide covers the schema changes your MCP clients will see, the removed APIs, and how to bring your own session IDs.

Compatibility

	mark3labs/mcp-go	modelcontextprotocol/go-sdk
Supported versions	v0.53.0 – v0.57.0	v1.4.1 – v1.7.0
Installs with	v0.57.0	v1.7.0
Stateless 2026-07-28 transports	✅	✅
stdio / streamable HTTP	✅	✅
Per-request server factories	✅	✅
MRTR tagging	— (not in mcp-go)	v1.7.0+
Go	1.25+	1.25+

You do not have to upgrade your MCP library to adopt v2. go.mod pins the newest version, so a fresh go get is unchanged — but if your project pins an older release in the supported range, the adapter compiles and tracks against it. The one exception is mcp-go below v0.53.0: v2 installs its middleware through MCPServer.Use, so bump mcp-go when you move to v2.

Also since v1.0.0

Everything merged between v1.0.0 and v2.0.0 makes its first stable-tag appearance here:

• Telemetry exporters — otlp, datadog, sentry, and posthog backends with per-exporter fault isolation, plus a telemetry-only mode (empty project ID with at least one exporter configured).
• EventTags / EventProperties — per-event tags (validated client-side) and arbitrary JSON properties from your own callbacks.
• PublishCustomEvent — publish your own agentcat:custom events alongside captured tool calls.
• RedactEvent hook — event-level redaction that sees the full eve...

v1.0.0 — AgentCat Go SDK

MCPcat is now AgentCat 🐱 — same team, same product, new name. First stable release of the AgentCat Go SDK.

go get go.agentcat.com/sdk@v1.0.0

Submodules (tagged alongside): go.agentcat.com/sdk/mcpgo@v1.0.0, go.agentcat.com/sdk/officialsdk@v1.0.0.

Nothing breaks if you stay — the old github.com/mcpcat/mcpcat-go-sdk module remains published and un-retracted; existing version pins keep resolving. Migrate on your own schedule — see MIGRATION.md.