feat: add MCP collections service, publishing, and catalog UI by subomi · Pull Request #2199 · speakeasy-api/gram

subomi · 2026-04-13T22:38:31Z

Summary

Adds collections CRUD endpoints (create, list, update, delete) and server attach/detach
Adds frontend pages for collections (list, create, detail) with org sidebar navigation
Makes registry_id optional across deployments/external MCP types for collection-backed servers
Handles internal Gram-hosted servers in tool extraction process
Auto-creates the default Registry collection and namespace on login and org scope switch

Rebased onto main now that #2198 is merged.

Test plan

go test github.com/speakeasy-api/gram/server/internal/auth
Create a collection via org settings -> collections -> create
Publish a toolset to the collection
Browse catalog and see collection servers
Install a server from the collection into a project
Verify installed server works (tools/list, tools/call)

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

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 · 2026-04-13T22:38:36Z

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

Project	Deployment	Actions	Updated (UTC)
gram-docs-redirect	Ready	Preview, Comment	Apr 15, 2026 7:54pm

changeset-bot · 2026-04-13T22:38:40Z

🦋 Changeset detected

Latest commit: a40e3a5

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

This PR includes changesets to release 2 packages

Name	Type
server	Minor
dashboard	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 · 2026-04-13T22:39:15Z

🚀 Preview Environment (PR #2199)

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

Component	Status	Details	Updated (UTC)
✅ Database	Ready	Existing database reused	2026-04-15 20:00:12.
✅ Images	Available	Container images ready	2026-04-15 19:59:55.

_{Gram Preview Bot}

devin-ai-integration

Devin Review found 5 potential issues.

View 4 additional findings in Devin Review.

devin-ai-integration · 2026-04-13T22:42:58Z

+func pgText(s *string) pgtype.Text {
+	if s == nil || *s == "" {
+		return pgtype.Text{String: "", Valid: false}
+	}
+	return pgtype.Text{String: *s, Valid: true}
+}


🟡 pgText treats empty string as NULL, preventing users from clearing collection description

The pgText helper at server/internal/collections/impl.go:358-363 returns {Valid: false} (SQL NULL) for both nil and empty string "". In the Update method (line 162), this means COALESCE(NULL, description) preserves the old value. A user who wants to clear a collection's description by sending description: "" will have their change silently ignored — the old description persists.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-04-13T22:43:03Z

+		if registry.Namespace != "" {
+			specifier = fmt.Sprintf("%s/%s", registry.Namespace, t.McpSlug.String)
+		}
+		collectionRegistryIDStr := registry.ID.String()


🚩 ListServers uses zero-value registry struct when registry row not found

At server/internal/collections/impl.go:372-375, if GetOrganizationMcpCollectionRegistryByID returns pgx.ErrNoRows, the error is silently ignored and registry remains a zero-value OrganizationMcpCollectionRegistry struct. This means registry.Namespace will be "" (line 393 check passes) and registry.ID will be uuid.Nil, which gets serialized as "00000000-0000-0000-0000-000000000000" in the OrganizationMcpCollectionRegistryID field of the response (line 396). If a collection somehow doesn't have a registry row (which shouldn't happen in normal flow but could after a data inconsistency), clients would receive a nil-UUID registry ID rather than null, which could cause confusion.

Was this helpful? React with 👍 or 👎 to provide feedback.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Ensure each organization gets a default Registry collection and namespace when a user logs in or switches scopes, with auth tests covering the bootstrap path. Made-with: Cursor

…ns-v3 Made-with: Cursor # Conflicts: # .speakeasy/workflow.lock # client/sdk/.speakeasy/gen.lock # client/sdk/.speakeasy/gen.yaml # client/sdk/jsr.json # client/sdk/package.json # client/sdk/src/lib/config.ts # client/sdk/src/models/operations/index.ts # server/gen/http/openapi3.json

devin-ai-integration

Devin Review found 3 new potential issues.

View 7 additional findings in Devin Review.

devin-ai-integration · 2026-04-14T02:47:05Z

+		if registry.Namespace != "" {
+			specifier = fmt.Sprintf("%s/%s", registry.Namespace, t.McpSlug.String)
+		}
+		collectionRegistryIDStr := registry.ID.String()


🔴 ListServers produces bogus nil-UUID collection registry ID when registry row is missing

In ListServers, when GetOrganizationMcpCollectionRegistryByID returns pgx.ErrNoRows, the error is silently swallowed (line 392) and the code continues with a zero-value registry struct. At line 415, registry.ID.String() produces "00000000-0000-0000-0000-000000000000", which is then set as OrganizationMcpCollectionRegistryID on every returned server. When the frontend subsequently installs these servers via a deployment, it sends this nil-UUID as the organization_mcp_collection_registry_id. The backend XOR validation passes (one ID is set), but during async deployment processing at server/internal/externalmcp/process.go:102, the code would try to use this invalid reference, and the FK constraint to organization_mcp_collection_registries would reject it. By contrast, the sibling List method at server/internal/collections/impl.go:174 treats a missing registry as a hard error, making this silent fallthrough inconsistent.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-04-14T02:47:06Z


 var AddExternalMCPForm = Type("AddExternalMCPForm", func() {
-	Required("registry_id", "name", "slug", "registry_server_specifier")
+	Required("name", "slug", "registry_server_specifier")


🚩 registryId made optional is a breaking change for existing API consumers

The AddExternalMCPForm type's registryId field changed from required (string) to optional (*string) in the Go types at server/gen/deployments/service.go:68-69 and correspondingly in the OpenAPI spec. The Required array in the design (server/design/deployments/design.go:352) no longer includes registry_id. Existing API consumers that always provide registry_id won't break, but any consumers relying on the response always having registry_id populated (e.g., the DeploymentExternalMCP type) will see a breaking change. The client SDK was regenerated to handle this, but external SDK users or direct API consumers may need updating.

Was this helpful? React with 👍 or 👎 to provide feedback.

Not relevant. We don't have any public consumers.

devin-ai-integration · 2026-04-14T02:47:08Z

+  const attachedToolsetIds = useMemo(() => {
+    const ids = new Set<string>();
+    for (const toolset of allToolsets) {
+      if (attachedMcpSlugs.has(toolset.mcpSlug)) {
+        ids.add(toolset.id);
+      }
+    }
+    return ids;
+  }, [allToolsets, attachedMcpSlugs]);


🚩 Collection attachedToolsetIds matching uses mcpSlug which may not be unique across projects

In CollectionDetail.tsx:146-154, attachedToolsetIds is built by matching toolsets' mcpSlug against the attachedMcpSlugs set derived from server registry specifiers. If two toolsets in different projects happen to share the same mcpSlug, both will appear as 'attached' even if only one is actually in the collection. This could cause incorrect checkbox states in the edit form and incorrect diff calculations when saving (potentially detaching the wrong toolset). The mcpSlug is extracted from the last segment of registrySpecifier at line 99-100, which further increases collision risk.

Was this helpful? React with 👍 or 👎 to provide feedback.

Initialize pgtype.Text explicitly so the default Registry bootstrap passes the stricter server lint rules after the merge from main. Made-with: Cursor

Restore the MCP Details publishing section so toolsets can be attached to or detached from collections directly from the settings page. Made-with: Cursor

Reject publishing for toolsets that are not enabled MCP servers and hide those toolsets from the collections UI so published servers persist after refresh. Made-with: Cursor

disintegrator · 2026-04-14T09:48:04Z

+		Result(MCPCollection)
+
+		HTTP(func() {
+			PATCH("/rpc/collections.update")


We're not patching in this operation and we generally don't have any APIs that take in patches on resources.

Suggested change

PATCH("/rpc/collections.update")

POST("/rpc/collections.update")

disintegrator · 2026-04-14T09:57:49Z

-					SelectedRemotes:         mcp.SelectedRemotes,
+					AttachmentID:                        mcp.ID,
+					RegistryID:                          mcp.RegistryID,
+					OrganizationMcpCollectionRegistryID: mcp.OrganizationMcpCollectionRegistryID,


Is there a shorter name for this field? Also a little confusing to have it alongside RegistryID. Should they be named InternalRegistryID and ExternalRegistryID or something like that?

Also are they mutually exclusive? If so, should there be some logic in deployments service to ensure that only one is provided?

Is there a shorter name for this field? Also a little confusing to have it alongside RegistryID. Should they be named InternalRegistryID and ExternalRegistryID or something like that?

I think the current naming is clear enough in context. If you don't have any strong objections, I'm happy to keep it as is for now. WDYT?

disintegrator · 2026-04-14T10:04:30Z

+-- name: GetOrganizationMcpCollectionByID :one
+SELECT id, organization_id, name, description, slug, visibility, created_at, updated_at
+FROM organization_mcp_collections
+WHERE id = @id AND deleted IS FALSE;


All queries must be qualified with either project id or organization id. In this case case:

Suggested change

WHERE id = @id AND deleted IS FALSE;

WHERE

id = @id

AND organization_id = @organization_id

AND deleted IS FALSE;

In the application layer, you pass ActiveOrganizationID and then you can check for pgx.ErrNoRows to assert that a collection exists or not.

disintegrator · 2026-04-14T10:05:16Z

+    description = COALESCE(sqlc.narg('description'), description),
+    visibility = COALESCE(sqlc.narg('visibility'), visibility),
+    updated_at = clock_timestamp()
+WHERE id = @id AND deleted IS FALSE


Needs to be qualified with org id here as well (authCtx.ActiveOrganizationID in code)

disintegrator · 2026-04-14T10:08:23Z

+	return &gen.ListServersResult{Servers: servers}, nil
+}
+
+func pgText(s *string) pgtype.Text {


Use the conv.PtrToPGTextEmpty

disintegrator · 2026-04-14T10:20:48Z

+		}
+		return oops.E(oops.CodeUnexpected, err, "get collection").Log(ctx, s.logger)
+	}
+	if existing.OrganizationID != authCtx.ActiveOrganizationID {


disintegrator · 2026-04-14T10:21:23Z

+		if !t.McpSlug.Valid {
+			continue
+		}
+		remoteURL := fmt.Sprintf("%s/mcp/%s", s.serverURL.String(), t.McpSlug.String)


use s.serverURL.JoinPath instead of fmt.Sprintf

disintegrator · 2026-04-14T10:21:36Z

+		}
+		specifier := t.McpSlug.String
+		if registry.Namespace != "" {
+			specifier = fmt.Sprintf("%s/%s", registry.Namespace, t.McpSlug.String)


use s.serverURL.JoinPath

disintegrator · 2026-04-14T10:23:39Z

+	return pgtype.Text{String: *s, Valid: true}
+}
+
+func toMCPCollection(c repo.CreateOrganizationMcpCollectionRow, namespace string) *types.MCPCollection {


Consider conv.FromPGText, conv.PtrEmpty

disintegrator · 2026-04-14T10:35:01Z


 		externalMCPID := r.ExternalMcpID.UUID
 		if externalMCPID != uuid.Nil && !seenExternalMCPs[externalMCPID] {
+			hasRegistry := r.ExternalMcpRegistryID.Valid && r.ExternalMcpRegistryID.UUID != uuid.Nil


use conv.FromNullableUUID and it should help clean up the pointer assignments below

devin-ai-integration

Devin Review found 1 new potential issue.

View 21 additional findings in Devin Review.

devin-ai-integration · 2026-04-15T14:00:44Z

      setPhase("configure");
    }
-  }, [servers]);
+  }, [servers, existingSpecifiers]);


🚩 useEffect dependency on existingSpecifiers may cause infinite re-partitioning loop

At useExternalMcpReleaseWorkflow.ts:197, the useEffect that initializes server configs now depends on [servers, existingSpecifiers]. Since existingSpecifiers is a useMemo that creates a new Set on every recomputation (line 130-138), it will have a new reference whenever latestDeployment?.externalMcps changes. After a deployment completes and useLatestDeployment refetches, this could trigger the useEffect to re-run and re-partition servers, potentially resetting the workflow state mid-flow. In practice, the deployment flow has already moved past the configure phase by then, but the re-partitioning could reset multiRemoteConfigs and serverConfigs unexpectedly. The Set reference stability depends on whether useMemo's [latestDeployment?.externalMcps] dependency changes reference between refetches.

Was this helpful? React with 👍 or 👎 to provide feedback.

adaam2 · 2026-04-15T15:40:26Z

+  // Clean up Radix body scroll-lock on unmount (e.g. when navigating away mid-dialog)
+  useEffect(() => {
+    return () => {
+      document.body.style.removeProperty("pointer-events");
+    };
+  }, []);
+


I don't think this is necessary

adaam2

I had a play with the preview app - everything seemed to work and its much improved. Had a quick breeze over the frontend code, and it looked 👍🏻

Approving for frontend. Waiting on Georges feedback on backend code.

disintegrator · 2026-04-15T16:06:47Z

 	var empty projectsRepo.Project
 	if err != nil {
-		if errors.As(err, &pgErr) && pgErr.Code == pgerrcode.UniqueViolation {
+		if isUniqueViolation(err) {


This change isn't relevant to the PR right? Can we revert it along with the helper function introduced below.

disintegrator · 2026-04-15T16:35:46Z

+		orgSlug = orgMeta.Slug
+	}
+
+	if err := s.ensureDefaultRegistryCollection(ctx, authCtx.ActiveOrganizationID, orgSlug); err != nil {


good idea to move here versus auth service 👍

devin-ai-integration

Devin Review found 2 new potential issues.

View 27 additional findings in Devin Review.

devin-ai-integration · 2026-04-15T19:09:30Z

      setPhase("configure");
    }
-  }, [servers]);
+  }, [servers, existingSpecifiers]);


🔴 Adding existingSpecifiers to useEffect deps causes phase reset mid-deployment

The useEffect at line 161 that partitions servers into multi/single remote now includes existingSpecifiers in its dependency array (line 197). When a deployment completes, latestDeployment is refetched, which causes existingSpecifiers to update (the newly installed servers are now in the set). This triggers the useEffect to re-run, which re-partitions servers (filtering out the just-installed ones), resets serverConfigs to empty, and unconditionally calls setPhase("configure") (line 195) — overwriting the current "complete" or "deploying" phase. This disrupts the completion UI (which shows toolset creation progress) by abruptly resetting to an empty configure phase.

Trigger scenario

User installs servers from a collection

Deployment starts → phase is "deploying"

Deployment completes → latestDeployment refetches → existingSpecifiers updates

useEffect re-runs, filters out all installed servers, calls setPhase("configure")

UI jumps from completion/deploying status to an empty configure screen

Prompt for agents

In useExternalMcpReleaseWorkflow.ts, the useEffect that partitions servers (starting around line 161) now has existingSpecifiers in its dependency array at line 197. This causes the effect to re-run when latestDeployment refetches after a successful deployment, which resets the phase and serverConfigs in the middle of active deployment or completion. The fix should add a guard at the top of the useEffect to bail out if the workflow is in an active phase (deploying, complete, or error). For example: if (phase === 'deploying' || phase === 'complete' || phase === 'error') return; This ensures the effect only partitions servers during the initial setup phases (configure/selectRemotes) when existingSpecifiers changes, not during active deployment.

Was this helpful? React with 👍 or 👎 to provide feedback.

devin-ai-integration · 2026-04-15T19:09:31Z

+	for _, idStr := range payload.ToolsetIds {
+		toolsetID, parseErr := uuid.Parse(idStr)
+		if parseErr != nil {
+			continue
+		}
+		if err := s.attachServerToCollection(ctx, cr, collection.ID, toolsetID, authCtx.ActiveOrganizationID, authCtx.UserID); err != nil {
+			return nil, err
+		}


🚩 CreateCollection does not filter non-MCP-enabled toolsets during creation

In CreateCollection, the toolsetIds array is iterated and each ID is passed to attachServerToCollection. Inside that function (impl.go:440), there's a check if !toolset.McpEnabled || !toolset.McpSlug.Valid that correctly rejects non-MCP-enabled toolsets. So invalid toolset IDs will cause the entire Create to fail with an error (line 131-133 returns the error). This means if a user provides even one non-MCP toolset ID, the whole collection creation fails. This might be intentional strictness, but could also be surprising since invalid UUIDs at line 128-129 are silently skipped while valid-but-ineligible toolsets cause a hard failure.

Was this helpful? React with 👍 or 👎 to provide feedback.

feat: MCP collections service, publishing, and catalog UI

113a567

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

subomi requested review from a team as code owners April 13, 2026 22:38

claude bot reviewed Apr 13, 2026

View reviewed changes

subomi mentioned this pull request Apr 13, 2026

feat: MCP collections service, publishing, and catalog UI #2174

Closed

5 tasks

github-actions bot added the preview Spawn a preview environment label Apr 13, 2026

subomi changed the title ~~feat: MCP collections service, publishing, and catalog UI~~ feat: add MCP collections service, publishing, and catalog UI Apr 13, 2026

devin-ai-integration bot reviewed Apr 13, 2026

View reviewed changes

chore: fix formatting in collections pages

c544b53

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview April 13, 2026 22:44 View deployment

chore: regenerate openapi3.json

cbfabcf

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview April 13, 2026 22:48 View deployment

This comment was marked as resolved.

Sign in to view

fix: auto-create default Registry collection on auth.

b2aea1d

Ensure each organization gets a default Registry collection and namespace when a user logs in or switches scopes, with auth tests covering the bootstrap path. Made-with: Cursor

vercel bot deployed to Preview April 14, 2026 02:29 View deployment

This comment was marked as resolved.

Sign in to view

vercel bot deployed to Preview April 14, 2026 02:42 View deployment

devin-ai-integration bot reviewed Apr 14, 2026

View reviewed changes

fix: satisfy auth lint checks.

cffb4f7

Initialize pgtype.Text explicitly so the default Registry bootstrap passes the stricter server lint rules after the merge from main. Made-with: Cursor

vercel bot deployed to Preview April 14, 2026 02:50 View deployment

feat: add collection publishing to MCP settings.

9fada0e

Restore the MCP Details publishing section so toolsets can be attached to or detached from collections directly from the settings page. Made-with: Cursor

vercel bot deployed to Preview April 14, 2026 04:11 View deployment

fix: keep collection publishing in sync with MCP state.

b30f6b9

Reject publishing for toolsets that are not enabled MCP servers and hide those toolsets from the collections UI so published servers persist after refresh. Made-with: Cursor

vercel bot deployed to Preview April 14, 2026 04:28 View deployment

disintegrator reviewed Apr 14, 2026

View reviewed changes

chore: resolve comments

16a6c41

chore: resilience

041fd38

vercel bot deployed to Preview April 15, 2026 13:51 View deployment

devin-ai-integration bot reviewed Apr 15, 2026

View reviewed changes

Merge branch 'main' into backend/mcp-collections-v3

1795143

vercel bot deployed to Preview April 15, 2026 14:50 View deployment

This comment has been minimized.

Sign in to view

chore: server and client regen

571dbc5

vercel bot deployed to Preview April 15, 2026 14:56 View deployment

chore: fixed linter issues

141ddaa

vercel bot deployed to Preview April 15, 2026 15:06 View deployment

adaam2 reviewed Apr 15, 2026

View reviewed changes

adaam2 approved these changes Apr 15, 2026

View reviewed changes

disintegrator approved these changes Apr 15, 2026

View reviewed changes

chore: qualify queries and resolve frontend stale code

a118863

vercel bot deployed to Preview April 15, 2026 18:51 View deployment

chore: server regen

c59dce3

vercel bot deployed to Preview April 15, 2026 18:56 View deployment

devin-ai-integration bot reviewed Apr 15, 2026

View reviewed changes

chore: add return early

1e6a26b

vercel bot deployed to Preview April 15, 2026 19:39 View deployment

This comment has been minimized.

Sign in to view

This comment was marked as resolved.

Sign in to view

chore: fixed failing test

d2fad64

vercel bot deployed to Preview April 15, 2026 19:47 View deployment

chore: resolve installed check

a40e3a5

vercel bot deployed to Preview April 15, 2026 19:54 View deployment

subomi merged commit ea1e23d into main Apr 15, 2026
29 checks passed

subomi deleted the backend/mcp-collections-v3 branch April 15, 2026 20:15

github-actions bot locked and limited conversation to collaborators Apr 15, 2026

	PATCH("/rpc/collections.update")
	POST("/rpc/collections.update")

Conversation

subomi commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

claude bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

vercel bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

speakeasybot commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 Preview Environment (PR #2199)

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration bot Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devin-ai-integration bot Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Apr 14, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devin-ai-integration bot Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

devin-ai-integration bot left a comment

Choose a reason for hiding this comment

Uh oh!

subomi commented Apr 13, 2026 •

edited

Loading

vercel bot commented Apr 13, 2026 •

edited

Loading

changeset-bot bot commented Apr 13, 2026 •

edited

Loading

speakeasybot commented Apr 13, 2026 •

edited

Loading

devin-ai-integration bot Apr 13, 2026 •

edited

Loading

devin-ai-integration bot Apr 13, 2026 •

edited

Loading

devin-ai-integration bot Apr 14, 2026 •

edited

Loading

devin-ai-integration bot Apr 14, 2026 •

edited

Loading