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