`mcp.CallToolResult.StructuredContent`: what is its usage?

[katiehockman]

It's unclear if CallToolResult.StructuredContent should ever be used vs just returning the generic type.

For example, the following code works fine:

(1)

type SessionsResult struct {
	Sessions []Session `json:"sessions"`
}

func ListSessions(ctx context.Context, _ *mcp.CallToolRequest, _ any) (*mcp.CallToolResult, SessionsResult, error) {
	return nil, SessionsResult{Sessions: sessions()}, nil
}

The following used to work in the previous version of the code, but now causes an error in Cursor when testing:

(2)

type SessionsResult struct {
	Sessions []Session `json:"sessions"`
}

func ListSessions(ctx context.Context, _ *mcp.CallToolRequest, _ any) (*mcp.CallToolResult, SessionsResult, error) {
	return &mcp.CallToolResult{
		StructuredContent: SessionsResult{Sessions: sessions()},
	}, SessionsResult{}, nil
}

which yields the following error message:

"error":"MCP error -32602: Structured content does not match the tool's output schema: data.sessions should be array"

I think (1) is pretty clear, but with the latest version, v0.3.1, I'm not sure if there's a use case for StructuredContent anymore. I don't see any examples in this repo which show when it would be needed either. Should StructuredContent just be removed as a return field?

[jba]

What you're seeing here and in #385 is our desire to retain everything in the protocol, like StructuredContent and IsError, while also providing a convenience layer. We expect everyone to use the convenience layer and ignore those two fields in the output, but we still want to leave a way for people to do everything from scratch.

When you use the top-level AddTool, it sets StructuredContent and IsError for you, as you can see here.

If you were to use Server.AddTool, your ToolHandler would have to do that itself, as well as validating the input and output schemas.

We'll improve the docs, and perhaps add an example of Server.AddTool (although I'd rather that no one used it).

[katiehockman]

I see, thanks @jba 👍

Fixing the docs should help with that, as you say, even just a line that says something like "In most cases, you should just return the content via the generic type in the result parameters. This type should only be used for [X special case]".

Alternatively, if you suspect that 99% of users won't need that type (which I think is likely true), then perhaps ToolHandlerFor should just omit that, with a different type for this specific case. e.g.

// A ToolHandlerFor handles a call to tools with typed arguments and results.
type ToolHandlerFor[In, Out any] func(context.Context, In) (Out, error)

// A ToolCallHandlerFor handles a call to tools/call with typed arguments and results that
// allows access to all fields in the MCP protocol, as well as fields related to the current
// client-server session. In most cases, you should use ToolHandlerFor.
type ToolCallHandlerFor[In, Out any] func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)

This assumes that type ToolHandler func(context.Context, *CallToolRequest) (*CallToolResult, error) doesn't have many strong use cases on its own such that it's okay to just have a generic type that can be ignored if needed.

I suspect that this will be much easier for people to understand and use on the average case.

If there really needs to be different types for generics and non-generics handlers, you could do this:

// A ToolHandlerFor handles a call to tools with typed arguments and results.
type ToolHandlerFor[In, Out any] func(context.Context, In) (Out, error)

// A ToolCallHandlerFor handles a call to tools/call with typed arguments and results that
// allows access to all fields in the MCP protocol, as well as fields related to the current
// client-server session. In most cases, you should use ToolHandlerFor.
type ToolCallHandlerFor[In, Out any] func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)

// A ToolCallHandler handles a call to tools/call with results that
// allows access to all fields in the MCP protocol, as well as fields related to the current
// client-server session. In most cases, you should use ToolHandlerFor.
type ToolCallHandler func(context.Context, *CallToolRequest) (*CallToolResult, error)

LMK if you want to discuss more!

[katiehockman]

To add more justification, the above proposal would allow code to change from this:

type SessionsResult struct {
	Sessions []Session `json:"sessions"`
}

func ListSessions(ctx context.Context, _ *mcp.CallToolRequest, _ any) (*mcp.CallToolResult, SessionsResult, error) {
	return nil, SessionsResult{Sessions: sessions()}, nil
}

to this:

type SessionsResult struct {
	Sessions []Session `json:"sessions"`
}

func ListSessions(ctx context.Context, _ any) (SessionsResult, error) {
	return SessionsResult{Sessions: sessions()}, nil
}

which is much easier to understand and read at a glance and may actually allow people to plug in some of their existing functions directly into an MCP server tool without any code refactors, which is kinda neat.

[jba]

The problem with that is that when you do want CallToolResult, you have to add back a lot to get it: basically all of the handler that ToolFor builds.

And I'm not sure that 99% of tools won't need it. If you look at our examples (which admittedly may not be representative), some set Content. (e.g. https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/memory/kb.go#L443)

[jba]

It is easy to write an adapter:

func SimpleTool[In, Out any](h func(context.Context, In) (Out, error)) ToolHandlerFor[In, Out] {
    ... 
}

If there's enough demand for it, we could add it ourselves. That would help if you have a pre-existing function, but if you're writing a custom one it's not really much more work to write in the two extra parameters than to call the adapter.

Another alternative is to have mcp.AddSimpleTool. Or we could flip it: AddTool is the simple case (exactly as you suggest), and AddFullTool includes the extra params.

/cc @findleyr @samthanawalla

[jba]

That last one (redefining AddTool) requires a proposal, and fast.

[katiehockman]

@jba I'm happy to write up a proposal if that's helpful. Does it need to go through the formal Go proposal process or is just a comment on this issue okay?

And I'm not sure that 99% of tools won't need it. If you look at our examples (which admittedly may not be representative), some set Content. (e.g. https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/memory/kb.go#L443)

In that example, I'm not really sure the content is actually important or valuable to the MCP client though? Would omitting the "Entities created successfully" affect the AI Agent in any meaningful way? I doubt it would, as if there was a problem it would have just returned an error. I don't see any examples in that file that show any real necessity for using the Content field, so I'm not yet convinced that this is going to be a common use case.

[jba]

In the interest of time, I wrote the proposal myself (see link above). @katiehockman feel free to add to it. Also /cc @findleyr.