feat: initial remote MCP source management UI

[bflad]

Summary

Implements AGE-1719 — the day-0 dashboard UI for the new Remote MCP source type, gated behind the gram-remote-mcp PostHog flag. Lets users register an external MCP server by URL and manage it with full CRUD without touching the catalog or deployment surface.

What's in this PR

Backend:

• Extends mcpServers.list with optional remote_mcp_server_id and toolset_id filters so the detail page's MCP Servers tab can scope to a single backend. The two filters are mutually exclusive (the mcp_servers schema's mcp_servers_backend_exclusivity_check already guarantees exactly one backend per row, so a query that pinned both would always be empty).
• Adds a remoteMcp.verifyURL RPC that probes a candidate URL with an MCP initialize request and reports a verification outcome.
• Adds an optional human-readable name and a URL-derived slug to remote_mcp_servers; slug is computed server-side on every write from the URL host+path and the last four characters of the id, and getServer accepts mutually-exclusive id or slug parameters.

Dashboard — gated behind gram-remote-mcp:

• Add Source dropdown gains a Custom remote server entry (lucide Network, violet swatch). Existing Third party server entry renamed to Registry server to disambiguate from the new flow.
• New create form at /sources/add-remote-mcp with a URL field, an optional Display Name field, a Verify MCP Connectivity button (calls remoteMcp.verifyURL), and absolute-http(s) + non-empty-host validation that mirrors the server's url.Parse checks.
• New detail page at /sources/remotemcp/:slug (with id fallback) modeled on ExternalMCPDetails.tsx. Three hash-routed tabs: Overview (Source Information table + Source Activity panel mirroring the OpenAPI source layout — Activity renders a structural empty state pending telemetry wiring tracked in AGE-2213 and AGE-2214), MCP Servers (cards for mcp_servers rows whose backend points at this remote MCP server), Settings (Display Name + URL edit with Verify MCP Connectivity button, plus Danger Zone delete).
• Source listing card and table row gain a remotemcp variant on NamedAsset with a Remote MCP badge; the display label prefers the server name and falls back to the URL with the protocol stripped. Card click routes into the new detail page.
• Existing RemoveSourceDialogContent and ViewAssetDialogContent narrow their asset prop to exclude remotemcp since those flows only handle deployment-bound sources.
• Form and Settings validation errors surface as inline alert boxes.

Orchestration

The backend doesn't expose a single transactional RPC for the compound create/delete operations the issue describes, so the create and delete flows live in pages/sources/remote-mcp/hooks.ts:

• useCreateRemoteMcpSource — calls remoteMcp.createServer, then mcpServers.create with the new id and visibility: "disabled". On partial failure (mcp_server create fails) it attempts to roll back the remoteMcp row; if rollback also fails, surfaces the orphaned id so the user can clean up manually.
• useDeleteRemoteMcpSource — soft-deletes each linked mcp_servers row first (which cascades to mcp_endpoints server-side), then deletes the remoteMcp row. The confirmation dialog enumerates linked servers and their endpoints up front so the user understands the full fan-out before confirming.

Both hooks invalidate remoteMcp.listServers, mcpServers.list, and mcpEndpoints.list with refetchType: "all" on success so the index, detail, and dialog caches stay coherent across navigation.

Follow-ups

• Full MCP server, custom domain, and MCP endpoint management beyond the auto-provision-on-create scaffolding is tracked in AGE-2118.
• Source Activity telemetry wiring for Remote MCP Server sources — ClickHouse telemetry_logs schema change (AGE-2213) and the dashboard wiring on top (AGE-2214).

[linear-code]

AGE-1719 Initial Remote MCP Source Management UI

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
gram-docs-redirect	Ready	Preview, Comment	May 8, 2026 1:40pm

[changeset-bot]

🦋 Changeset detected

Latest commit: 86a161d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
dashboard	Minor
server	Minor

Not sure what this means? Click here to learn what changesets are.

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

[speakeasybot]

🚀 Preview Environment (PR #2608)

Preview URL: https://pr-2608.dev.getgram.ai

Component	Status	Details	Updated (UTC)
✅ Database	Ready	Existing database reused	2026-05-08 13:45:17.
✅ Images	Available	Container images ready	2026-05-08 13:45:00.

_{Gram Preview Bot}

[simplesagar]

Nice work! Some feedback on the UX primarily on the state post adding a server by url, screenshot below

1. I think we need a display name that's easier for customers to reference rather than just the long id eg: https://pr-2608.dev.getgram.ai/speakeasy-team/projects/default/sources/remotemcp/019dfd85-a73e-76f0-8cc9-41c579064bcf
2. If we can we should materialise the remote tools into a list on this page as a new tab. See tabs for other source types as inspiration
3. on the settings tab it let me update to a url that was invalid whereas in the initial setup step it does not
4. in the initial setup step there's a nice warning below the entry box indicating validity of the URL. We should highlight/color that text to make it stand out as a warning.

Other ideas

• you could probably lift and shift the source overview tab (table and activity overview) we have for other source types
• We show a filtered view of deployments for other sources. We could probably do something similar here.

[bflad]

Thanks, @simplesagar!

I think we need a display name that's easier for customers to reference rather than just the long id

I agree, I do think we need some form of (display) name. I'm not sure about using it as slug as that'll have URL path character requirements then. Either which way (whether just name or name + slug) can get that added into the backend real quick. Using the URL everywhere leaves much to be desired.

If we can we should materialise the remote tools into a list on this page as a new tab. See tabs for other source types as inspiration

Is there a particular reason? A few of us are thinking we should only do this when working with policies and we should only do this during management of those. Getting the list requires authentication and we don't want to store this sort of data if avoidable (one of the problems with the existing implementation).

on the settings tab it let me update to a url that was invalid whereas in the initial setup step it does not

Will get that sorted, good catch.

in the initial setup step there's a nice warning below the entry box indicating validity of the URL. We should highlight/color that text to make it stand out as a warning.

Will also get this sorted, thank you.

you could probably lift and shift the source overview tab (table and activity overview) we have for other source types

Will reach out to you about this.

We show a filtered view of deployments for other sources. We could probably do something similar here.

We need to handle this differently for Registry MCP / Remote MCP. They're intentionally not using the toolset deployment model. Let me have a think about this, we might be able to augment the deployments page with audit logging for these sources or something so it shows similar information.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View 11 additional findings in Devin Review.

[simplesagar]

Thanks for addressing the feedback Brian!

Is there a particular reason? A few of us are thinking we should only do this when working with policies and we should only do this during management of those. Getting the list requires authentication and we don't want to store this sort of data if avoidable (one of the problems with the existing implementation).

Primary reason is that it when a user adds in a source its an unusual experience not to be able to see what tools you are bringing into the system. There is also a matter of inconsistency between http, function, external and remote sources. I'm not opposed to asking the user to auth just in time during the process of adding a remote mcp. I think that ensures they are the right person to add in the source too.

[bflad]

We chatted about the tools listing vs security configuration awkwardness out of band. We'll create a way to handle that (either via wizard and/or some handling on these pages) such that you can go through the security configuration and persist it, rather than it potentially being temporary just to get the tools list. We just want to ensure there's one way to do that rather than introducing multiple UI journeys to manage.