feat: list and call tools from external MCPs #1057

qstearns · 2025-12-12T00:53:55Z

Implements runtime tool listing and calling for external MCP servers. Proxy tools (tools:externalmcp:<slug>:proxy) are "unfolded" at runtime to expose the actual tools from the external MCP server.

Key changes:

unfoldExternalMCPTools() in MCP RPC handlers - expands proxy tools to actual tools via ListToolsFromProxy()
handleExternalMCPToolCall() - routes tool calls to external MCP servers via session API
doExternalMCP() in gateway proxy - handles tool execution with OAuth token passthrough
GetToolCallPlanByURN() updated to handle ToolKindExternalMCP
conv.ToBaseTool() returns error for proxy tools (must be unfolded first)
RAG search and agents updated to unfold proxy tools before processing

Tool naming convention: External MCP tools are named as <slug>:<toolname> (e.g., notion:search, github:list_repos).

Summary

external-mcp/5/list-and-call: URN kind and design types - Add ToolKindExternalMCP
external-mcp/5/list-and-call: implementation using generated types - Core unfolding and calling logic
external-mcp/5/list-and-call: instances, toolsets, and tests - Integration with instances API and test updates

🤖 Generated with Claude Code

changeset-bot · 2025-12-12T00:53:58Z

⚠️ No Changeset found

Latest commit: 4bd3ffd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2025-12-12T00:53:59Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
gram	Ready	Preview, Comment	Dec 17, 2025 7:40pm
gram-docs-redirect	Ready	Preview, Comment	Dec 17, 2025 7:40pm
gram-landing-redirect	Ready	Preview, Comment	Dec 17, 2025 7:40pm

ryan-timothy-albert · 2025-12-12T01:36:00Z

server/internal/mcp/rpc_tools_list.go

 		tools = buildToolListEntries(toolset.Tools)
+
+		// Unfold proxy tools from external MCP servers
+		unfoldedTools, err := unfoldExternalMCPTools(ctx, logger, toolset.Tools, payload.oauthTokenInputs)


So checking my understanding here. It seems like we actually only unfold an external tool in mcp context. So right now these tools wouldn't be visible/useable in the playground. Correct?

…nd-call-tools

chase-crumbaugh · 2025-12-17T03:03:12Z

server/internal/conv/tools.go

+func ToToolListEntry(tool *types.Tool) (name, description string, inputSchema json.RawMessage, meta map[string]any, err error) {
 	if tool == nil {
-		return "", "", nil, nil
+		return "", "", nil, nil, nil


I draw the line at five return params lol
Wrap that baby in a struct

yeah that baby belongs in a struct. ✅

chase-crumbaugh · 2025-12-17T03:04:47Z

server/internal/gateway/models.go

+}
+
+// NewExternalMCPToolCallPlan creates a new Tool wrapping an ExternalMCPTool.
+func NewExternalMCPToolCallPlan(tool *ToolDescriptor, plan *ExternalMCPToolCallPlan) *ToolCallPlan {


Im surprised the Plan for this isn't the same as HTTP

I think that there are some differences for sure:

for instance, the way you want to map input configuration to source configuration is way less complex for external MCP in that you don't have to worry about all the Header vs Body vs Param configuration options of open API + formatting options Open API supports. Also no notion of something like request method

chase-crumbaugh · 2025-12-17T03:07:30Z

server/internal/mcp/impl.go

 	}

+	// Pre-resolve external MCP OAuth config for use in switch
+	fullToolset, descErr := mv.DescribeToolset(ctx, s.logger, s.db, mv.ProjectID(toolset.ProjectID), mv.ToolsetSlug(toolset.Slug), &s.toolsetCache)


Do we need the FULL toolset? DescribeToolset is somewhat expensive

Does wellKnown get spammed or am i misremembering

https://app.datadoghq.com/logs?query=service%3Agram-server%20%40url.original%3A%2F.well-known%2F%2A&agg_m=count&agg_m_source=base&agg_q=%40url.original&agg_t=count&clustering_pattern_field_path=message&cols=host%2Cservice&flat_group_bys=true&messageDisplay=inline&refresh_mode=sliding&sort_m=count&sort_t=count&storage=hot&stream_sort=desc&top_n=10&top_o=top&viz=timeseries&x_missing=true&from_ts=1765906267874&to_ts=1765992667874&live=true

well-known gets traffic but not a ton. All of it is from Polar. Even so I refactored to short-circuit before describe toolset in order to ensure that if there is a latency spike that we're going to avoid it

chase-crumbaugh · 2025-12-17T03:09:31Z

server/internal/mcp/impl.go

 	}

+	// TODO: Consider caching hasExternalMCPOAuth on the toolset record to avoid loading
+	// the full toolset on every request just to check OAuth requirements.


Yes lets definitely do that. Alternatively you can add a query that just retrieves the information needed for oauth instead of loading the entire toolet

I have a ticket draft for this which I can tag you on for discussion. I don't think it's a matter of just storing it on the toolset. It interfaces with other OAuth concepts in pretty complicated ways, so I was hoping to peel off the actual abstraction work into a separately reviewed PR

chase-crumbaugh · 2025-12-17T03:10:52Z

server/internal/mcp/impl.go

 				Token:        externalSecret.Token,
 			})
 		}
+	case toolset.McpIsPublic && hasExternalMCPOAuth:


I already thought all this oauth stuff needed to be factored out of this method even before this addition. Let's figure out a way to encapsulate the oauth logic elsewhere. At the very least make a ticket with a link to this method saying to refactor

Have a ticket drafted for this. I need to wrap my head around the implications of Walker's recent changes if I'm going to have any hope of making a refactor here a net improvement

chase-crumbaugh · 2025-12-17T03:11:35Z

server/internal/mcp/rpc_tools_call.go

 		metrics.RecordMCPToolCall(ctx, toolset.OrganizationID, mcpURL, params.Name)
 	}

+	// Check if this is an external MCP tool call (format: "slug:toolname")


Is that refactor coming in a later pr

The version implemented here uses the tool name format. I'll follow up with another PR alongside support for instances.

qstearns

Left a few responses. Addressed some of the feedback here but also would prefer to keep some of this work scoped to linear tickets. Stuff like refactoring our oauth logic I think is just gonna require a slightly more holistic view of the system than what I want to bite off as the scope of this PR

qstearns · 2025-12-17T19:41:24Z

server/internal/mcp/impl.go

 	}

+	// Pre-resolve external MCP OAuth config for use in switch
+	fullToolset, descErr := mv.DescribeToolset(ctx, s.logger, s.db, mv.ProjectID(toolset.ProjectID), mv.ToolsetSlug(toolset.Slug), &s.toolsetCache)


https://app.datadoghq.com/logs?query=service%3Agram-server%20%40url.original%3A%2F.well-known%2F%2A&agg_m=count&agg_m_source=base&agg_q=%40url.original&agg_t=count&clustering_pattern_field_path=message&cols=host%2Cservice&flat_group_bys=true&messageDisplay=inline&refresh_mode=sliding&sort_m=count&sort_t=count&storage=hot&stream_sort=desc&top_n=10&top_o=top&viz=timeseries&x_missing=true&from_ts=1765906267874&to_ts=1765992667874&live=true

well-known gets traffic but not a ton. All of it is from Polar. Even so I refactored to short-circuit before describe toolset in order to ensure that if there is a latency spike that we're going to avoid it

qstearns · 2025-12-17T19:42:26Z

server/internal/mcp/impl.go

 	}

+	// TODO: Consider caching hasExternalMCPOAuth on the toolset record to avoid loading
+	// the full toolset on every request just to check OAuth requirements.


I have a ticket draft for this which I can tag you on for discussion. I don't think it's a matter of just storing it on the toolset. It interfaces with other OAuth concepts in pretty complicated ways, so I was hoping to peel off the actual abstraction work into a separately reviewed PR

qstearns · 2025-12-17T19:43:16Z

server/internal/mcp/impl.go

 				Token:        externalSecret.Token,
 			})
 		}
+	case toolset.McpIsPublic && hasExternalMCPOAuth:


Have a ticket drafted for this. I need to wrap my head around the implications of Walker's recent changes if I'm going to have any hope of making a refactor here a net improvement

qstearns · 2025-12-17T19:46:08Z

server/internal/mcp/rpc_tools_call.go

 		metrics.RecordMCPToolCall(ctx, toolset.OrganizationID, mcpURL, params.Name)
 	}

+	// Check if this is an external MCP tool call (format: "slug:toolname")


The version implemented here uses the tool name format. I'll follow up with another PR alongside support for instances.

qstearns · 2025-12-17T19:46:18Z

server/internal/gateway/models.go

+}
+
+// NewExternalMCPToolCallPlan creates a new Tool wrapping an ExternalMCPTool.
+func NewExternalMCPToolCallPlan(tool *ToolDescriptor, plan *ExternalMCPToolCallPlan) *ToolCallPlan {


I think that there are some differences for sure:

for instance, the way you want to map input configuration to source configuration is way less complex for external MCP in that you don't have to worry about all the Header vs Body vs Param configuration options of open API + formatting options Open API supports. Also no notion of something like request method

qstearns requested a review from a team as a code owner December 12, 2025 00:53

vercel bot deployed to Preview – gram December 12, 2025 00:55 View deployment

qstearns force-pushed the external-mcp/5/list-and-call-tools branch from ed21dda to 0b97202 Compare December 12, 2025 00:55

qstearns force-pushed the external-mcp/4/oauth branch from 91f5cbf to 60aa2a0 Compare December 12, 2025 00:55

vercel bot deployed to Preview – gram-docs-redirect December 12, 2025 00:55 View deployment

vercel bot deployed to Preview – gram-landing-redirect December 12, 2025 00:55 View deployment

vercel bot deployed to Preview – gram December 12, 2025 00:57 View deployment

ryan-timothy-albert reviewed Dec 12, 2025

View reviewed changes

qstearns force-pushed the external-mcp/4/oauth branch from 60aa2a0 to af7c803 Compare December 15, 2025 22:55

external-mcp/4/oauth: OAuth handling for external MCPs

64417e0

qstearns force-pushed the external-mcp/5/list-and-call-tools branch from 0b97202 to 643abc0 Compare December 16, 2025 04:18

vercel bot deployed to Preview – gram-docs-redirect December 16, 2025 04:18 View deployment

vercel bot deployed to Preview – gram December 16, 2025 04:20 View deployment

qstearns added 7 commits December 16, 2025 14:05

external-mcp/5/list-and-call: URN kind and design types

eaabbc0

external-mcp/5/list-and-call: implementation using generated types

6fc88c8

external-mcp/5/list-and-call: instances, toolsets, and tests

3be4f8a

update client interface

1377acc

fix type on external mcp

8a8b3ae

fix dumb

7f55167

Merge remote-tracking branch 'origin/main' into external-mcp/5/list-a…

108dfcc

…nd-call-tools

qstearns force-pushed the external-mcp/5/list-and-call-tools branch from 643abc0 to 108dfcc Compare December 16, 2025 22:06

vercel bot deployed to Preview – gram-docs-redirect December 16, 2025 22:06 View deployment

vercel bot deployed to Preview – gram December 16, 2025 22:08 View deployment

qstearns added 2 commits December 16, 2025 15:15

Clean up OAuth resolution logic a little bit

6d856b5

[wip] allow proxy toolsets on install page

9e9ec83

vercel bot deployed to Preview – gram-docs-redirect December 16, 2025 23:17 View deployment

qstearns changed the base branch from external-mcp/4/oauth to main December 16, 2025 23:18

vercel bot deployed to Preview – gram December 16, 2025 23:19 View deployment

improve error handling and such

310fc54

vercel bot deployed to Preview – gram-docs-redirect December 17, 2025 00:16 View deployment

vercel bot deployed to Preview – gram December 17, 2025 00:18 View deployment

qstearns changed the title ~~feat: List and call tools from external MCPs~~ feat: list and call tools from external MCPs Dec 17, 2025

chase-crumbaugh reviewed Dec 17, 2025

View reviewed changes

chase-crumbaugh approved these changes Dec 17, 2025

View reviewed changes

qstearns added 4 commits December 17, 2025 09:47

address some PR feedback

b958f2d

add wellknown package to oauth

defd222

fix linter errors

d0f4d5d

fix deferring behavior

4bd3ffd

vercel bot deployed to Preview – gram-docs-redirect December 17, 2025 19:39 View deployment

vercel bot deployed to Preview – gram December 17, 2025 19:40 View deployment

qstearns commented Dec 17, 2025

View reviewed changes

qstearns mentioned this pull request Dec 17, 2025

feat: OAuth handling for external MCPs #1056

Closed

qstearns merged commit eadbcc2 into main Dec 18, 2025
24 checks passed

qstearns deleted the external-mcp/5/list-and-call-tools branch December 18, 2025 00:35

github-actions bot locked and limited conversation to collaborators Dec 18, 2025

feat: list and call tools from external MCPs #1057

feat: list and call tools from external MCPs #1057

Uh oh!

Conversation

qstearns commented Dec 12, 2025

Summary

Uh oh!

changeset-bot bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel bot commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qstearns left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot bot commented Dec 12, 2025 •

edited

Loading

vercel bot commented Dec 12, 2025 •

edited

Loading