Files
coder/codersdk/mcp.go
T
Michael Suchacz 35cbca080e feat: allow sharing MCP servers with users and groups (#28593)
## Summary

Adds the missing user-facing half of MCP server config ACLs: admins can
now share an MCP server with individual users and groups from the UI,
backed by a new permission-safe candidate-discovery endpoint.

## Problem

The MCP server config ACL backend already existed (share RBAC action,
hydrated `GET .../acl`, sparse `PATCH .../acl`), but there was no
frontend for it. There was also no way to populate a sharing
autocomplete without the generic organization member/group APIs, which
require `organization_member:read` and `group:read` and would wrongly
couple MCP sharing to the workspace-sharing mode (the same bug fixed for
chat models in #28542).

## Changes

Backend:

- New v2-only `GET
/api/v2/organizations/{organization}/mcp-servers/{mcpserverconfig}/acl/available`
returning `codersdk.ACLAvailable`; because this API is new, it is not
mounted under the experimental compatibility prefix. Gated on
`ActionShare` for the specific server config; performs bounded
org-scoped member/group lookups via `dbauthz.AsSystemRestricted`;
excludes system users; supports `q`, `limit`, `offset`, and `after_id`
with template/chat-model autocomplete semantics.
- Tests cover authorization (404 without share), search, pagination,
system-user exclusion, org scoping, and a share-only custom role under
all three workspace-sharing modes (`none`, `service_accounts`,
`everyone`).

Frontend:

- `shareMCPServerConfig` permission plumbing; the MCP servers list,
details page, and AI settings sidebar now admit share-only users (share
does not require update; share-only users cannot edit the server form).
- Share-only access follows the established permission contract: a
bare-share role manages sharing through the list and ACL endpoints (the
detail route still requires read, update, or delete, matching the
existing enterprise permission-matrix tests), and the disabled-config
gate now also admits the share permission so a sharer with read access
can open a disabled server. Top-level navigation (Admin settings menu
and the /ai/settings index redirect) discovers organization-level MCP
sharers and surfaces permission lookup failures instead of silently
falling back.
- "Share server" action on the MCP server edit page opening a sharing
dialog: hydrated ACL grants render from the `GET .../acl` response,
adds/removals are saved as sparse `PATCH` deltas (`"read"` / `""`).
- Principal autocomplete backed exclusively by the new `/acl/available`
endpoint; the sharing flow never calls the generic org member/group APIs
(Storybook enforces this by rejecting those API spies). A discovery
error surfaces under the autocomplete without hiding existing grants.
- Storybook interaction coverage for the dialog (hydrated rendering,
add/remove, sparse deltas, error/cancel/reopen paths, autocomplete
exclusion and failure) and share-only access to the page/form.

Dogfood UAT ran remotely against a dev instance and passed, including
verifying via the network log that candidate discovery only hits
`/acl/available`. The share-only custom role UI flow could not be
exercised there (no premium license on the dev instance); it is covered
by the backend permission-matrix tests.

> 🤖 This PR was authored by Xum (an AI coding agent) acting on Mike's
behalf.
2026-08-26 19:49:43 +02:00

326 lines
13 KiB
Go

package codersdk
import (
"context"
"fmt"
"net/http"
"time"
"github.com/google/uuid"
)
// MCPServerOAuth2ConnectURL returns the URL the user should visit to
// start the OAuth2 flow for an MCP server. The frontend opens this
// in a new window/popup.
func (c *Client) MCPServerOAuth2ConnectURL(organizationID, id uuid.UUID) string {
return fmt.Sprintf("%s/api/v2/organizations/%s/mcp-servers/%s/oauth2/connect", c.URL.String(), organizationID, id)
}
// MCPServerOAuth2DisconnectResponse reports whether the removed token
// was also revoked at the OAuth provider.
type MCPServerOAuth2DisconnectResponse struct {
TokenRevoked bool `json:"token_revoked"`
TokenRevocationError string `json:"token_revocation_error,omitempty"`
}
// MCPServerOAuth2Disconnect removes the user's OAuth2 token for an
// MCP server. Use MCPServerOAuth2DisconnectWithResponse for the
// provider revocation outcome.
func (c *Client) MCPServerOAuth2Disconnect(ctx context.Context, id uuid.UUID) error {
_, err := c.MCPServerOAuth2DisconnectWithResponse(ctx, id)
return err
}
// MCPServerOAuth2DisconnectWithResponse removes the user's OAuth2
// token for an MCP server and reports the provider revocation outcome.
func (c *Client) MCPServerOAuth2DisconnectWithResponse(ctx context.Context, id uuid.UUID) (MCPServerOAuth2DisconnectResponse, error) {
res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/mcp/servers/%s/oauth2/disconnect", id), nil)
if err != nil {
return MCPServerOAuth2DisconnectResponse{}, err
}
defer res.Body.Close()
// Servers from before provider revocation respond 204 without a body.
if res.StatusCode == http.StatusNoContent {
return MCPServerOAuth2DisconnectResponse{}, nil
}
if res.StatusCode != http.StatusOK {
return MCPServerOAuth2DisconnectResponse{}, ReadBodyAsError(res)
}
var resp MCPServerOAuth2DisconnectResponse
return resp, ReadBodyAsJSON(res, &resp)
}
// MCPServerConfig represents an admin-configured MCP server.
type MCPServerConfig struct {
ID uuid.UUID `json:"id" format:"uuid"`
OrganizationID uuid.UUID `json:"organization_id" format:"uuid"`
DisplayName string `json:"display_name"`
Slug string `json:"slug"`
Description string `json:"description"`
IconURL string `json:"icon_url"`
Transport string `json:"transport"` // "streamable_http" or "sse"
URL string `json:"url"`
AuthType string `json:"auth_type"` // "none", "oauth2", "api_key", "custom_headers", "user_oidc"
// OAuth2 fields (only populated for admins).
OAuth2ClientID string `json:"oauth2_client_id,omitempty"`
HasOAuth2Secret bool `json:"has_oauth2_secret"`
OAuth2AuthURL string `json:"oauth2_auth_url,omitempty"`
OAuth2TokenURL string `json:"oauth2_token_url,omitempty"`
OAuth2RevocationURL string `json:"oauth2_revocation_url,omitempty"`
OAuth2Scopes string `json:"oauth2_scopes,omitempty"`
// API key fields (only populated for admins).
APIKeyHeader string `json:"api_key_header,omitempty"`
HasAPIKey bool `json:"has_api_key"`
HasCustomHeaders bool `json:"has_custom_headers"`
// Tool governance.
ToolAllowList []string `json:"tool_allow_list"`
ToolDenyList []string `json:"tool_deny_list"`
// Availability policy set by admin.
Availability string `json:"availability"` // "force_on", "default_on", "default_off"
Enabled bool `json:"enabled"`
ModelIntent bool `json:"model_intent"`
AllowInPlanMode bool `json:"allow_in_plan_mode"`
// ForwardCoderHeaders forwards the same Coder identity headers we
// send to LLM providers (X-Coder-Owner-Id, X-Coder-Chat-Id, and the
// optional X-Coder-Subchat-Id and X-Coder-Workspace-Id) to this
// MCP server on every request. Off by default to avoid leaking
// chat identity to third-party servers.
ForwardCoderHeaders bool `json:"forward_coder_headers"`
CreatedAt time.Time `json:"created_at" format:"date-time"`
UpdatedAt time.Time `json:"updated_at" format:"date-time"`
// Per-user state (populated for non-admin requests).
AuthConnected bool `json:"auth_connected"`
}
// MCPServerConfigRole is a role a user or group holds in an MCP server
// config's access control list.
type MCPServerConfigRole string
const (
MCPServerConfigRoleRead MCPServerConfigRole = "read"
// MCPServerConfigRoleDeleted removes the principal's ACL entry when
// used in an update request.
MCPServerConfigRoleDeleted MCPServerConfigRole = ""
)
// MCPServerConfigACL is the resolved access control list of an MCP server
// config.
type MCPServerConfigACL struct {
Users []MCPServerConfigUser `json:"users"`
Groups []MCPServerConfigGroup `json:"groups"`
}
// MCPServerConfigUser is a user entry in an MCP server config ACL.
type MCPServerConfigUser struct {
MinimalUser
Role MCPServerConfigRole `json:"role" enums:"read"`
}
// MCPServerConfigGroup is a group entry in an MCP server config ACL.
type MCPServerConfigGroup struct {
Group
Role MCPServerConfigRole `json:"role" enums:"read"`
}
// UpdateMCPServerConfigACLRequest is a sparse update of an MCP server
// config ACL: only the listed principals change, and
// MCPServerConfigRoleDeleted removes an entry.
type UpdateMCPServerConfigACLRequest struct {
UserRoles map[string]MCPServerConfigRole `json:"user_roles,omitempty"`
GroupRoles map[string]MCPServerConfigRole `json:"group_roles,omitempty"`
}
// CreateMCPServerConfigRequest is the request to create a new MCP server config.
type CreateMCPServerConfigRequest struct {
DisplayName string `json:"display_name" validate:"required"`
Slug string `json:"slug" validate:"required"`
Description string `json:"description"`
IconURL string `json:"icon_url"`
Transport string `json:"transport" validate:"required,oneof=streamable_http sse"`
URL string `json:"url" validate:"required,url"`
AuthType string `json:"auth_type" validate:"required,oneof=none oauth2 api_key custom_headers user_oidc"`
OAuth2ClientID string `json:"oauth2_client_id,omitempty"`
OAuth2ClientSecret string `json:"oauth2_client_secret,omitempty"`
OAuth2AuthURL string `json:"oauth2_auth_url,omitempty" validate:"omitempty,url"`
OAuth2TokenURL string `json:"oauth2_token_url,omitempty" validate:"omitempty,url"`
// OAuth2RevocationURL is the provider's RFC 7009 revocation
// endpoint; auto-populated by OAuth2 discovery when omitted.
OAuth2RevocationURL string `json:"oauth2_revocation_url,omitempty" validate:"omitempty,url"`
OAuth2Scopes string `json:"oauth2_scopes,omitempty"`
APIKeyHeader string `json:"api_key_header,omitempty"`
APIKeyValue string `json:"api_key_value,omitempty"`
CustomHeaders map[string]string `json:"custom_headers,omitempty"`
ToolAllowList []string `json:"tool_allow_list,omitempty"`
ToolDenyList []string `json:"tool_deny_list,omitempty"`
Availability string `json:"availability" validate:"required,oneof=force_on default_on default_off"`
Enabled bool `json:"enabled"`
ModelIntent bool `json:"model_intent"`
AllowInPlanMode bool `json:"allow_in_plan_mode"`
// ForwardCoderHeaders, when true, forwards Coder identity
// headers on every outgoing MCP request. See MCPServerConfig.
ForwardCoderHeaders bool `json:"forward_coder_headers"`
}
// UpdateMCPServerConfigRequest is the request to update an MCP server config.
type UpdateMCPServerConfigRequest struct {
DisplayName *string `json:"display_name,omitempty"`
Slug *string `json:"slug,omitempty"`
Description *string `json:"description,omitempty"`
IconURL *string `json:"icon_url,omitempty"`
Transport *string `json:"transport,omitempty" validate:"omitempty,oneof=streamable_http sse"`
URL *string `json:"url,omitempty" validate:"omitempty,url"`
AuthType *string `json:"auth_type,omitempty" validate:"omitempty,oneof=none oauth2 api_key custom_headers user_oidc"`
OAuth2ClientID *string `json:"oauth2_client_id,omitempty"`
OAuth2ClientSecret *string `json:"oauth2_client_secret,omitempty"`
OAuth2AuthURL *string `json:"oauth2_auth_url,omitempty" validate:"omitempty,url"`
OAuth2TokenURL *string `json:"oauth2_token_url,omitempty" validate:"omitempty,url"`
// OAuth2RevocationURL is validated in the handler because a
// validate tag would reject the pointer to "" that clears it.
OAuth2RevocationURL *string `json:"oauth2_revocation_url,omitempty"`
OAuth2Scopes *string `json:"oauth2_scopes,omitempty"`
APIKeyHeader *string `json:"api_key_header,omitempty"`
APIKeyValue *string `json:"api_key_value,omitempty"`
CustomHeaders *map[string]string `json:"custom_headers,omitempty"`
ToolAllowList *[]string `json:"tool_allow_list,omitempty"`
ToolDenyList *[]string `json:"tool_deny_list,omitempty"`
Availability *string `json:"availability,omitempty" validate:"omitempty,oneof=force_on default_on default_off"`
Enabled *bool `json:"enabled,omitempty"`
ModelIntent *bool `json:"model_intent,omitempty"`
AllowInPlanMode *bool `json:"allow_in_plan_mode,omitempty"`
// ForwardCoderHeaders, when set, updates whether Coder identity
// headers are forwarded on every outgoing MCP request.
ForwardCoderHeaders *bool `json:"forward_coder_headers,omitempty"`
}
func (c *Client) MCPServerConfigs(ctx context.Context, organizationID uuid.UUID) ([]MCPServerConfig, error) {
res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers", organizationID), nil)
if err != nil {
return nil, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return nil, ReadBodyAsError(res)
}
var configs []MCPServerConfig
return configs, ReadBodyAsJSON(res, &configs)
}
func (c *Client) MCPServerConfigByID(ctx context.Context, organizationID, id uuid.UUID) (MCPServerConfig, error) {
res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s", organizationID, id), nil)
if err != nil {
return MCPServerConfig{}, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return MCPServerConfig{}, ReadBodyAsError(res)
}
var config MCPServerConfig
return config, ReadBodyAsJSON(res, &config)
}
// MCPServerConfigACL returns the resolved ACL of an MCP server config.
func (c *Client) MCPServerConfigACL(ctx context.Context, organizationID, id uuid.UUID) (MCPServerConfigACL, error) {
res, err := c.Request(ctx, http.MethodGet, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s/acl", organizationID, id), nil)
if err != nil {
return MCPServerConfigACL{}, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return MCPServerConfigACL{}, ReadBodyAsError(res)
}
var acl MCPServerConfigACL
return acl, ReadBodyAsJSON(res, &acl)
}
// MCPServerConfigACLAvailable returns available users and groups that can be
// assigned to an MCP server config ACL.
func (c *Client) MCPServerConfigACLAvailable(ctx context.Context, organizationID, id uuid.UUID, req UsersRequest) (ACLAvailable, error) {
res, err := c.Request(ctx, http.MethodGet,
fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s/acl/available", organizationID, id),
nil,
req.Pagination.asRequestOption(),
req.asRequestOption(),
)
if err != nil {
return ACLAvailable{}, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return ACLAvailable{}, ReadBodyAsError(res)
}
var available ACLAvailable
return available, ReadBodyAsJSON(res, &available)
}
// UpdateMCPServerConfigACL applies a sparse ACL update to an MCP server
// config.
func (c *Client) UpdateMCPServerConfigACL(ctx context.Context, organizationID, id uuid.UUID, req UpdateMCPServerConfigACLRequest) error {
res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s/acl", organizationID, id), req)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode != http.StatusNoContent {
return ReadBodyAsError(res)
}
return nil
}
func (c *Client) CreateMCPServerConfig(ctx context.Context, organizationID uuid.UUID, req CreateMCPServerConfigRequest) (MCPServerConfig, error) {
res, err := c.Request(ctx, http.MethodPost, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers", organizationID), req)
if err != nil {
return MCPServerConfig{}, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusCreated {
return MCPServerConfig{}, ReadBodyAsError(res)
}
var config MCPServerConfig
return config, ReadBodyAsJSON(res, &config)
}
func (c *Client) UpdateMCPServerConfig(ctx context.Context, organizationID, id uuid.UUID, req UpdateMCPServerConfigRequest) (MCPServerConfig, error) {
res, err := c.Request(ctx, http.MethodPatch, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s", organizationID, id), req)
if err != nil {
return MCPServerConfig{}, err
}
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
return MCPServerConfig{}, ReadBodyAsError(res)
}
var config MCPServerConfig
return config, ReadBodyAsJSON(res, &config)
}
func (c *Client) DeleteMCPServerConfig(ctx context.Context, organizationID, id uuid.UUID) error {
res, err := c.Request(ctx, http.MethodDelete, fmt.Sprintf("/api/v2/organizations/%s/mcp-servers/%s", organizationID, id), nil)
if err != nil {
return err
}
defer res.Body.Close()
if res.StatusCode != http.StatusNoContent {
return ReadBodyAsError(res)
}
return nil
}