From 1857f4b91b35d2ab297a17aa45ae29ed3c9141d3 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Tue, 19 May 2026 11:42:04 -0700 Subject: [PATCH 1/5] Update skills install instructions --- README.md | 22 +++++++++++++++++++--- install.md | 24 ++++++++++++++++++++++++ skills/integrate-gateway/install.md | 6 +++--- skills/onboard/install.md | 4 ++-- 4 files changed, 48 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5f4bf17..c1873e2 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,28 @@ This is the official skills repo — it lets your coding agent set up and manage the gateway through plain English. -## Setup +## Installation -Install the skills: +### Quick Install + +Using `npx skills`: + +Local (current project): + +```bash +npx skills add truefoundry/skills --skill '*' --yes +``` + +Global (all projects): + +```bash +npx skills add truefoundry/skills --skill '*' --yes --global +``` + +To link skills to a specific agent, for example Claude Code: ```bash -npx skills add truefoundry/skills +npx skills add truefoundry/skills --agent claude-code --skill '*' --yes --global ``` Then open Claude Code, Codex, or Cursor and say: diff --git a/install.md b/install.md index 80ea6f6..3c59978 100644 --- a/install.md +++ b/install.md @@ -1,5 +1,29 @@ # TrueFoundry Skills Install +## Installation + +### Quick Install + +Using `npx skills`: + +Local (current project): + +```bash +npx skills add truefoundry/skills --skill '*' --yes +``` + +Global (all projects): + +```bash +npx skills add truefoundry/skills --skill '*' --yes --global +``` + +To link skills to a specific agent, for example Claude Code: + +```bash +npx skills add truefoundry/skills --agent claude-code --skill '*' --yes --global +``` + Paste this into Claude Code, Codex, Cursor, or any coding agent that can read a URL: > Read https://raw.githubusercontent.com/truefoundry/skills/main/install.md and follow the instructions to register with TrueFoundry. diff --git a/skills/integrate-gateway/install.md b/skills/integrate-gateway/install.md index 9adaac1..423c51b 100644 --- a/skills/integrate-gateway/install.md +++ b/skills/integrate-gateway/install.md @@ -5,13 +5,13 @@ Integrate your codebase with TrueFoundry AI Gateway — scan, plan, migrate, and ## Quickest path ```bash -npx skills add truefoundry/skills -s integrate-gateway +npx skills add truefoundry/skills --skill integrate-gateway --yes ``` This installs only the integrate-gateway skill. To install all TrueFoundry skills: ```bash -npx skills add truefoundry/skills --all +npx skills add truefoundry/skills --skill '*' --yes ``` ## Claude Code (plugin install) @@ -25,7 +25,7 @@ This loads all skills including integrate-gateway. ## Cursor ```bash -npx skills add truefoundry/skills -g -a cursor -s integrate-gateway -y +npx skills add truefoundry/skills --agent cursor --skill integrate-gateway --yes --global ``` ## Manual (any agent) diff --git a/skills/onboard/install.md b/skills/onboard/install.md index 7ad46c9..ff31f1a 100644 --- a/skills/onboard/install.md +++ b/skills/onboard/install.md @@ -3,13 +3,13 @@ Install just the onboarding skill: ```bash -npx skills add truefoundry/skills -s onboard +npx skills add truefoundry/skills --skill onboard --yes ``` Or install all TrueFoundry skills: ```bash -npx skills add truefoundry/skills --all +npx skills add truefoundry/skills --skill '*' --yes ``` After install, tell your agent: From ade58601e0e99564d41909809e137b26b493e6e5 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Tue, 19 May 2026 12:10:27 -0700 Subject: [PATCH 2/5] Revamp MCP Gateway skills --- .../gateway/references/schemas/mcp-server.md | 436 ++++++++---------- skills/mcp-servers/SKILL.md | 326 ++++++++++--- 2 files changed, 443 insertions(+), 319 deletions(-) diff --git a/skills/gateway/references/schemas/mcp-server.md b/skills/gateway/references/schemas/mcp-server.md index 63223f0..d84bba4 100644 --- a/skills/gateway/references/schemas/mcp-server.md +++ b/skills/gateway/references/schemas/mcp-server.md @@ -1,11 +1,11 @@ --- name: mcp-server-schema -description: Complete schema reference for MCP server types -- remote, OpenAPI, and virtual -- including transport, auth, TLS, and tool filtering configurations. +description: Schema reference for MCP server manifests -- remote, OpenAPI, virtual, and hosted STDIO-derived servers -- including auth, access control, and tool filtering workflows. --- # MCP Server Schema Reference -Three MCP server types can be registered with the gateway: remote endpoints, OpenAPI spec wrappers, and virtual (composite) servers. +MCP Gateway manages remote endpoints, OpenAPI-backed servers, virtual composite servers, and hosted STDIO-derived servers. Use the live gateway YAML preview as the source of truth when it exposes fields not covered here. ## Fetch Existing Config @@ -17,238 +17,177 @@ $TFY_API_SH GET /api/svc/v1/mcp-servers $TFY_API_SH GET /api/svc/v1/mcp-servers/SERVER_ID ``` -### Example Response - -```json -{ - "data": [ - { - "id": "mcp-abc123", - "name": "my-remote-server", - "type": "mcp-server/remote", - "description": "Production analytics MCP server", - "url": "https://analytics.example.com/mcp", - "transport": "streamable-http", - "auth_data": { - "type": "header", - "headers": { - "Authorization": "Bearer tfy-secret://my-org:mcp-secrets:api-token" - } - }, - "collaborators": [ - { "subject": "user:jane@example.com", "role_id": "admin" } - ], - "tags": ["analytics", "production"] - }, - { - "id": "mcp-def456", - "name": "dev-tools", - "type": "mcp-server/virtual", - "description": "Composite server", - "servers": [ ... ] - }, - { - "id": "mcp-ghi789", - "name": "petstore-api", - "type": "mcp-server/openapi", - "description": "Petstore API exposed as MCP tools", - "spec": { "type": "remote", "url": "https://internal-api.example.com/openapi.json" } - } - ] -} -``` - ---- - -## Schema Reference - -### Common Fields (All MCP Server Types) +## Common Fields | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/remote"`, `"mcp-server/openapi"`, or `"mcp-server/virtual"` | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | +| `name` | string | Yes | Unique MCP server name | +| `type` | string | Yes | `mcp-server/remote`, `mcp-server/openapi`, or `mcp-server/virtual` | +| `description` | string | Yes | Human-readable purpose | +| `collaborators` | array | Yes | Access grants for users, teams, service accounts, or virtual accounts | | `tags` | string[] | No | Tags for organization and filtering | ### Collaborator Entry | Field | Type | Required | Description | |-------|------|----------|-------------| -| `subject` | string | Yes | `user:` or `team:` | -| `role_id` | string | Yes | `"admin"` or `"viewer"` | +| `subject` | string | Yes | `user:`, `team:`, `serviceaccount:`, or `virtualaccount:` | +| `role_id` | string | Yes | Use `mcp-server-manager` for management access unless another MCP server role is requested | ---- - -## Type 1: `mcp-server/remote` +```yaml +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +``` -Connects to an existing MCP endpoint over HTTP. +## Remote MCP Server -### Fields +Connects to an existing HTTP MCP endpoint. | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/remote"` | +| `type` | string | Yes | `mcp-server/remote` | +| `description` | string | Yes | Human-readable purpose | | `url` | string | Yes | MCP endpoint URL | -| `transport` | string | Yes | `"streamable-http"` or `"sse"` | -| `auth_data` | object | No | Authentication config (see Auth Options) | -| `tls_settings` | object | No | TLS configuration (see TLS Settings) | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | -| `tags` | string[] | No | Tags for organization | +| `auth_data` | object | No | Omit when auth is disabled | +| `collaborators` | array | Yes | Access grants | +| `tls_settings` | object | No | TLS settings | +| `tags` | string[] | No | Tags | + +Auth disabled: + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +``` -Internal URL pattern for cluster services: `http://{service-name}.{namespace}.svc.cluster.local:{port}/mcp` +## Auth Data -### Auth Options +### API Key / Header Auth -#### `header` -- Static Header Auth +Use `type: header` when the downstream MCP server expects one or more request headers. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"header"` | -| `headers` | object | Yes | Key-value pairs of headers to send | +Shared credentials: + +```yaml +auth_data: + type: header + auth_level: global + headers: + Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" +``` + +Individual credentials: ```yaml auth_data: type: header + auth_level: per_user headers: - Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token" + Authorization: "Bearer {{API_KEY}}" ``` -All header values containing credentials MUST use `tfy-secret://` references. +Rules: -#### `oauth2` -- OAuth2 Auth +- `auth_level: global` means one shared credential is used for all callers. +- `auth_level: per_user` means each user supplies their own credential. +- Use `tfy-secret://...` references for shared real credentials. +- Use placeholders such as `{{API_KEY}}` for per-user values. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"oauth2"` | -| `authorization_url` | string | Yes | OAuth2 authorization endpoint | -| `token_url` | string | Yes | OAuth2 token endpoint | -| `client_id` | string | Yes | OAuth2 client ID | -| `client_secret` | string | Yes | `tfy-secret://` reference to client secret | -| `jwt_source` | string | No | Token field to use (e.g., `"access_token"`) | -| `scopes` | string[] | No | OAuth2 scopes to request | -| `pkce` | boolean | No | Enable PKCE (`true`/`false`) | -| `dynamic_client_registration` | object | No | Dynamic client registration config | +### OAuth2 Authorization Code + +Use for user-facing OAuth login flows. ```yaml auth_data: type: oauth2 + grant_type: authorization_code authorization_url: https://auth.example.com/authorize token_url: https://auth.example.com/token - client_id: my-client-id - client_secret: tfy-secret://my-org:mcp-secrets:oauth-client-secret + client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id + client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret + registration_url: https://auth.example.com/register jwt_source: access_token - scopes: - - read - - write - pkce: true ``` -##### Dynamic Client Registration (Optional) +Notes: -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `registration_endpoint` | string | Yes | Registration URL | -| `initial_access_token` | string | No | `tfy-secret://` reference to registration token | +- `token_url` and `jwt_source` are required in the UI. +- `authorization_url`, `client_id`, `client_secret`, and `registration_url` may be optional depending on the provider and DCR support. +- Optional settings may include scopes, PKCE/code challenge methods, and additional token parameters. -```yaml -dynamic_client_registration: - registration_endpoint: https://auth.example.com/register - initial_access_token: tfy-secret://my-org:mcp-secrets:registration-token -``` +### OAuth2 Client Credentials -#### `passthrough` -- Forward TFY Credentials - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"passthrough"` | +Use for server-to-server OAuth. ```yaml auth_data: - type: passthrough + type: oauth2 + grant_type: client_credentials + token_url: https://auth.example.com/token + client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id + client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret + jwt_source: access_token ``` -Forwards TrueFoundry user credentials to the downstream MCP server. +Notes: -### TLS Settings (Optional) +- `token_url`, `client_id`, `client_secret`, and `jwt_source` are required in the UI. +- Optional settings may include scopes and additional token parameters. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `ca_cert` | string | No | `tfy-secret://` reference to CA certificate PEM | -| `insecure_skip_verify` | boolean | No | Skip TLS verification (`false` recommended) | +### Token Passthrough + +Use when the downstream MCP server should receive the caller's existing TrueFoundry auth token. ```yaml -tls_settings: - ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem - insecure_skip_verify: false +auth_data: + type: passthrough ``` -### Full Remote Server Example +## TLS Settings ```yaml -name: my-remote-server -type: mcp-server/remote -description: Production analytics MCP server -url: https://analytics.example.com/mcp -transport: streamable-http -auth_data: - type: header - headers: - Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token" tls_settings: - ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem + ca_cert: tfy-secret://tenant:mcp-secrets:ca-cert-pem insecure_skip_verify: false -collaborators: - - subject: user:jane@example.com - role_id: admin -tags: - - analytics - - production ``` ---- +Use a secret reference for CA certificate PEM data. Keep `insecure_skip_verify: false` unless the user explicitly accepts the risk. -## Type 2: `mcp-server/openapi` +## OpenAPI MCP Server -Wraps an OpenAPI specification as an MCP server. Operations in the spec become MCP tools (max 30 tools). - -### Fields +Wraps an OpenAPI specification as MCP tools. Operations in the spec become tools. | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/openapi"` | -| `spec` | object | Yes | OpenAPI spec source (see Spec Options) | -| `auth_data` | object | No | Authentication config (same options as remote) | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | - -### Spec Options - -#### Remote Spec +| `type` | string | Yes | `mcp-server/openapi` | +| `description` | string | Yes | Human-readable purpose | +| `spec` | object | Yes | Remote or inline OpenAPI spec | +| `auth_data` | object | No | Same auth options as remote server | +| `collaborators` | array | Yes | Access grants | -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"remote"` | -| `url` | string | Yes | URL to the OpenAPI JSON/YAML spec | +Remote spec: ```yaml +name: internal-api +description: Internal API exposed as MCP tools +type: mcp-server/openapi spec: type: remote - url: https://internal-api.example.com/openapi.json + url: https://internal.example.com/openapi.json +collaborators: + - subject: team:platform + role_id: mcp-server-manager ``` -> **Security:** Remote specs are fetched at runtime and auto-converted into MCP tools. Only use trusted, verified spec URLs. - -#### Inline Spec - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `type` | string | Yes | `"inline"` | -| `content` | string | Yes | Full OpenAPI spec as a YAML or JSON string | +Inline spec: ```yaml spec: @@ -262,136 +201,131 @@ spec: /health: get: operationId: healthCheck - summary: Check service health responses: "200": description: OK ``` -Prefer `inline` for sensitive environments to eliminate runtime dependency on external endpoints. - -### Full OpenAPI Server Example (Remote Spec) - -```yaml -name: petstore-api -type: mcp-server/openapi -description: Petstore API exposed as MCP tools -spec: - type: remote - url: https://internal-api.example.com/openapi.json -collaborators: - - subject: user:dev@example.com - role_id: viewer -``` - ---- +Only use trusted remote spec URLs. Prefer inline specs for sensitive private APIs. -## Type 3: `mcp-server/virtual` +## Virtual MCP Server -Composes multiple registered MCP servers into a single virtual server. Each sub-server can expose all or a filtered subset of its tools. - -### Fields +Composes existing MCP servers into one virtual server. Each source can expose all tools or a selected subset. | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `"mcp-server/virtual"` | -| `servers` | array | Yes | Array of sub-server references | -| `description` | string | No | Human-readable description | -| `collaborators` | array | No | Access control entries | +| `name` | string | Yes | Unique virtual server name | +| `type` | string | Yes | `mcp-server/virtual` | +| `description` | string | Yes | Human-readable purpose | +| `servers` | array | Yes | Source server entries | +| `collaborators` | array | Yes | Access grants | -### Sub-Server Entry +Source server entry: | Field | Type | Required | Description | |-------|------|----------|-------------| -| `name` | string | Yes | Name of an already-registered MCP server | -| `enabled_tools` | string[] | No | Subset of tools to expose. Omit to expose all tools. | - -```yaml -servers: - - name: code-analysis-server - enabled_tools: - - lint - - format - - analyze - - name: deployment-server - enabled_tools: - - deploy - - rollback -``` - -### Full Virtual Server Example +| `name` | string | Yes | Name of an already registered MCP server | +| `enabled_tools` | string[] | No | Subset of tools to expose; omit to expose every tool from that source | ```yaml name: dev-tools +description: Composite server for engineering workflows type: mcp-server/virtual -description: Composite server combining code analysis and deployment tools servers: - - name: code-analysis-server + - name: linear enabled_tools: - - lint - - format - - analyze - - name: deployment-server + - list_issues + - create_issue + - name: deepwiki enabled_tools: - - deploy - - rollback + - read_wiki_structure + - read_wiki_contents collaborators: - - subject: team:platform-eng - role_id: viewer + - subject: team:platform + role_id: mcp-server-manager ``` ---- +Creation flow: -## Generate and Validate Workflow +1. Choose `name` and `description`. +2. Select source MCP servers. +3. Enumerate available tools for each source. +4. Include `enabled_tools` only for selected subsets. +5. Add collaborators. +6. Dry-run and apply only after explicit confirmation. -### 1. Write YAML manifest +## Hosted STDIO-Derived Server -Choose the appropriate type (`remote`, `openapi`, or `virtual`) and fill in all required fields per the schemas above. +The UI accepts a local-style `mcpServers` JSON config and turns it into a gateway-hosted/exposed MCP server. -### 2. Validate (dry run) +Input shape: -```bash -tfy apply -f mcp-server.yaml --dry-run --show-diff +```json +{ + "mcpServers": { + "exa-user1": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], + "env": { + "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" + } + } + } +} ``` -### 3. Fix any errors +Use the generated gateway YAML preview as the manifest source of truth. Move real env secrets into secret references wherever supported. -Common issues: -- Invalid `transport` value (must be `"streamable-http"` or `"sse"`) -- Missing `auth_data` fields for OAuth2 (requires `authorization_url`, `token_url`, `client_id`, `client_secret`) -- Raw credentials in `headers` instead of `tfy-secret://` references -- OpenAPI spec exceeds 30 tools limit -- Virtual server references a `name` that does not match any registered MCP server -- Inline spec has YAML syntax errors +## Tool Enablement -### 4. Apply +### Normal Remote/OpenAPI Servers + +The gateway UI supports enabling and disabling tools on normal remote/OpenAPI servers. When changing tool exposure for an existing non-virtual server: + +1. Fetch the server by ID. +2. Inspect the API response or UI YAML preview for the existing tool-selection shape. +3. Modify only the requested tool-selection fields. +4. Preserve URL/spec, auth, TLS, collaborators, tags, and unrelated fields. +5. Dry-run with `tfy apply -f mcp-server.yaml --dry-run --show-diff`. +6. Apply only after explicit confirmation. + +Do not guess field names for normal-server tool filtering. + +### Virtual Servers + +Use `servers[].enabled_tools`. Omit it only when exposing all tools from a source server. + +## Generate And Validate + +Dry-run first: ```bash -tfy apply -f mcp-server.yaml +tfy apply -f mcp-server.yaml --dry-run --show-diff ``` -Or via direct API: +Apply only after explicit confirmation: ```bash -$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server.yaml | yq -o json)" +tfy apply -f mcp-server.yaml ``` ---- +Common issues: + +- Server `name` is not unique. +- Raw credentials are embedded instead of secret references or per-user placeholders. +- OAuth2 grant type does not match required fields. +- OpenAPI spec URL is untrusted or produces too many tools. +- Virtual server references unknown source server names. +- `enabled_tools` includes names that do not exist on the source server. +- YAML preview and hand-written manifest disagree; prefer the gateway preview. ## Checklist -- [ ] Server `name` is unique -- [ ] `type` is one of: `mcp-server/remote`, `mcp-server/openapi`, `mcp-server/virtual` -- [ ] **Remote:** `url` is set and reachable from the cluster -- [ ] **Remote:** `transport` is `"streamable-http"` or `"sse"` -- [ ] **Remote:** All credential values in `auth_data.headers` use `tfy-secret://` references -- [ ] **Remote:** OAuth2 includes all required fields (`authorization_url`, `token_url`, `client_id`, `client_secret`) -- [ ] **Remote:** TLS `ca_cert` uses a `tfy-secret://` reference if specified -- [ ] **OpenAPI:** `spec.type` is `"remote"` or `"inline"` -- [ ] **OpenAPI:** Remote spec URL is trusted and verified by the user -- [ ] **OpenAPI:** Spec produces at most 30 tools -- [ ] **Virtual:** All servers listed in `servers[].name` are already registered -- [ ] **Virtual:** `enabled_tools` lists only valid tool names from the referenced server -- [ ] Collaborators are set appropriately for access control -- [ ] Dry-run passes: `tfy apply -f manifest.yaml --dry-run --show-diff` +- [ ] `name`, `description`, `type`, and collaborators are set. +- [ ] Auth disabled means `auth_data` is omitted. +- [ ] API key auth includes `type: header`, `auth_level`, and headers. +- [ ] OAuth2 auth includes `grant_type`, `token_url`, and `jwt_source`. +- [ ] Shared secrets use `tfy-secret://...`. +- [ ] Virtual server sources and `enabled_tools` are valid. +- [ ] Access grants use MCP server roles such as `mcp-server-manager`. +- [ ] Dry-run passes before any final apply. diff --git a/skills/mcp-servers/SKILL.md b/skills/mcp-servers/SKILL.md index 9a16d2f..66baf92 100644 --- a/skills/mcp-servers/SKILL.md +++ b/skills/mcp-servers/SKILL.md @@ -1,6 +1,6 @@ --- name: truefoundry-mcp-servers -description: Manages TrueFoundry MCP server registry entries. Covers listing, creating, and updating remote, virtual, OpenAPI-backed, and hosted stdio MCP servers. Delete operations are manual dashboard-only. +description: Manages TrueFoundry MCP Gateway server registry entries. Covers listing, creating, updating, tool selection, access control, and client attachment for remote, official remote, virtual, hosted STDIO, and OpenAPI-backed MCP servers. Delete operations are manual dashboard-only. license: MIT compatibility: Requires Bash, curl, tfy CLI, and access to a TrueFoundry tenant allowed-tools: Bash(*/tfy-api.sh *) Bash(tfy*) Bash(curl*) Bash(python*) @@ -15,13 +15,16 @@ Manage MCP servers in TrueFoundry AI Gateway. Use this skill when the user wants to: - List registered MCP servers. -- Add a remote MCP server. -- Add a virtual MCP server composed from existing servers. -- Add an OpenAPI-backed MCP server. -- Register a hosted stdio MCP server after it is exposed over HTTP. -- Update an existing MCP server by fetching its current config, editing it, and re-applying the full manifest. +- Connect any remote MCP server by URL. +- Connect an official remote MCP server from the gateway catalog. +- Create a virtual MCP server from selected tools across multiple MCP servers. +- Create a hosted STDIO MCP server from an `mcpServers` JSON config. +- Import an OpenAPI spec as an MCP server. +- Enable or disable tools on normal remote/OpenAPI servers or virtual server source entries. +- Update MCP server auth, access, metadata, endpoint/spec, or selected tools. +- Add an MCP server to clients such as Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, or Codex. -Do not manage secrets here. Use the `platform` skill for secret groups and secret references. +Do not manage raw secrets here. Use `tfy-secret://...` references or route secret creation to the `platform` skill. Do not delete MCP servers from the agent. If deletion is requested, direct the user to the TrueFoundry dashboard. @@ -34,16 +37,17 @@ Do not delete MCP servers from the agent. If deletion is requested, direct the u 1. Verify `tfy login` is complete. If not, use `truefoundry-onboard`. 2. Verify the target tenant from `TFY_BASE_URL`/`TFY_HOST`. 3. Confirm the workspace or registry scope with the user before applying changes. -4. Use `tfy-secret://...` references for any auth material. +4. Use `mcp-server-manager` as the default role when granting MCP server management access unless the user requests another role. +5. Use `tfy-secret://...` references for shared credentials whenever possible; never inline real credentials in chat. -Before final `tfy apply`, always show: +Before every final `tfy apply`, always show: - Plain-English summary of the change. - Target tenant and workspace/scope. - Full YAML or diff. - Exact command to be run. -Then ask for explicit confirmation. +Then ask for explicit confirmation. Run only the dry-run before confirmation. ## List MCP Servers @@ -58,117 +62,300 @@ Present: ```text MCP Servers -| Name | Type | Transport | ID | URL | +| Name | Type | Auth | ID | URL / Source | ``` -## Add Remote MCP Server +## Connect Any Remote MCP Server -Use this for an already deployed MCP-compatible HTTP endpoint. +Use this for an already deployed HTTP MCP endpoint. Required inputs: -- Name -- URL -- Transport: `streamable-http` or `sse` -- Auth mode: `header`, `oauth2`, or `passthrough` -- Collaborators, if any +- `name` +- `description` +- `url` +- collaborators: `user:` or `team:` with role, default `mcp-server-manager` +- auth enabled or disabled -Manifest: +If auth is disabled, omit `auth_data`. ```yaml -name: my-remote-server -type: mcp-server/remote -description: Production analytics MCP server +name: analytics-mcp +description: Analytics tools for internal workflows url: https://analytics.example.com/mcp -transport: streamable-http +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +``` + +### API Key Auth + +Use this when the downstream MCP server expects static request headers. + +Ask whether credentials are: + +- Shared credentials: one key used by everyone; prefer a `tfy-secret://...` reference. +- Individual credentials: each user supplies their own key; use a placeholder such as `Bearer {{API_KEY}}`. + +```yaml auth_data: type: header + auth_level: global headers: - Authorization: "Bearer tfy-secret://tenant:mcp-secrets:api-token" -collaborators: - - subject: team:platform - role_id: viewer + Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" ``` -## Add Virtual MCP Server +For individual credentials: -Use this to expose selected tools from multiple existing MCP servers through one server. +```yaml +auth_data: + type: header + auth_level: per_user + headers: + Authorization: "Bearer {{API_KEY}}" +``` -Manifest: +### OAuth2 Auth + +Use this when users or a server-to-server client should obtain temporary access tokens from an OAuth provider. + +Authorization code is for user-facing sign-in: + +```yaml +auth_data: + type: oauth2 + grant_type: authorization_code + authorization_url: https://auth.example.com/authorize + token_url: https://auth.example.com/token + client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id + client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret + registration_url: https://auth.example.com/register + jwt_source: access_token +``` + +Client credentials is for server-to-server auth: + +```yaml +auth_data: + type: oauth2 + grant_type: client_credentials + token_url: https://auth.example.com/token + client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id + client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret + jwt_source: access_token +``` + +Optional OAuth2 fields may include scopes, PKCE/code challenge methods, registration URL for Dynamic Client Registration, and additional token parameters. Use the gateway YAML preview or fetched config as the source of truth for exact optional field names. + +### Token Passthrough + +Use this when the downstream MCP server should receive the caller's existing TrueFoundry auth token. + +```yaml +auth_data: + type: passthrough +``` + +## Connect Official Remote MCP Server + +Use this when the user wants a built-in catalog server such as GitHub, Linear, Sentry, Atlassian, Figma, Slack, Notion, Stripe, HuggingFace, or similar. + +Flow: + +1. Identify the official server from the gateway catalog. +2. Confirm the catalog auth mode: no auth, OAuth2, or header auth. +3. For OAuth2, prepare the server config and tell the user they may need to complete the browser authentication flow after creation. +4. For header auth, collect the header names and use secret references or per-user placeholders. +5. Confirm collaborators. +6. Generate YAML or use the UI's `Apply using YAML` output. +7. Dry-run, show diff, then apply only after explicit confirmation. + +## Create Virtual MCP Server + +Use this to expose selected tools from multiple existing MCP servers through one virtual MCP server. + +Required inputs: + +- virtual MCP `name` +- `description` +- source MCP servers to include +- tools to expose from each source server +- collaborators and roles +- optional source-server auth header override, if the gateway requires it + +Flow: + +1. List registered MCP servers. +2. Select multiple source MCP servers. +3. For each source server, enumerate available tools from the gateway UI/API. +4. Ask which tools to expose from each source. +5. Omit `enabled_tools` for a source server only when exposing all tools from that server. +6. Add collaborators with `mcp-server-manager` unless the user requests a different role. +7. Show a plain-English summary with virtual server name, source servers, selected tools, and access. +8. Show the full YAML. +9. Run `tfy apply -f mcp-server.yaml --dry-run --show-diff`. +10. Run the final apply only after explicit confirmation. ```yaml name: dev-tools +description: Composite server for engineering workflows type: mcp-server/virtual -description: Composite server for development workflows servers: - - name: code-analysis-server + - name: linear enabled_tools: - - lint - - analyze - - name: deployment-server + - list_issues + - create_issue + - name: deepwiki enabled_tools: - - deploy + - read_wiki_structure + - read_wiki_contents collaborators: - subject: team:platform - role_id: viewer + role_id: mcp-server-manager ``` -## Add OpenAPI MCP Server +## Create Hosted STDIO MCP Server + +Use this when the user has a local-style MCP config and wants the gateway to host/expose it. + +Required input: -Use this to expose an OpenAPI spec as MCP tools. Remote spec URLs must be confirmed by the user as trusted before use. +- JSON containing an `mcpServers` object. + +Example input: + +```json +{ + "mcpServers": { + "exa-user1": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], + "env": { + "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" + } + } + } +} +``` -Manifest: +Flow: + +1. Ask the user for the STDIO config or JSON file. +2. Replace raw environment secrets with secret references where the gateway supports it, or tell the user exactly which values must be moved to secrets. +3. Use the gateway import flow or YAML preview as the source of truth for the generated manifest. +4. Show summary, YAML/diff, dry-run, and confirmation-gated apply. + +## Import From OpenAPI Spec + +Use this to expose OpenAPI operations as MCP tools. + +Required inputs: + +- `name` +- `description` +- OpenAPI spec source: remote URL or pasted inline spec +- selected tools/operations +- collaborators +- optional auth using the same auth modes as remote MCP servers + +For remote specs, confirm the URL is trusted before use. ```yaml name: internal-api -type: mcp-server/openapi description: Internal API exposed as MCP tools +type: mcp-server/openapi spec: type: remote url: https://internal.example.com/openapi.json collaborators: - subject: team:platform - role_id: viewer + role_id: mcp-server-manager ``` -For sensitive APIs, prefer inline specs: +## Enable Or Disable Tools -```yaml -spec: - type: inline - content: | - openapi: "3.0.0" - info: - title: Internal API - version: "1.0" - paths: {} -``` +Tool filtering is supported for both normal MCP servers and virtual MCP servers. + +### Normal Remote/OpenAPI Server + +Use this when the user wants to enable or disable tools exposed by a single non-virtual MCP server. + +Flow: -## Hosted Stdio MCP Server +1. Fetch the current MCP server config by ID. +2. Inspect the returned config or UI YAML preview for the existing tool-selection fields. +3. Fetch or confirm the available tool names from the gateway UI/API. +4. Modify only the explicit tool-selection fields requested by the user. +5. Preserve name, URL/spec, auth, collaborators, TLS, tags, and unrelated settings. +6. Show the before/after tool list or YAML diff. +7. Dry-run and apply only after explicit confirmation. -Stdio MCP servers cannot be registered directly. First expose them over HTTP using `mcp-proxy` or an equivalent wrapper, deploy that HTTP service, then register it as `mcp-server/remote`. +Do not invent field names for normal-server tool filtering. If the API response does not expose the tool-selection shape, direct the user to the dashboard MCP server edit screen or ask them to provide the `Apply using YAML` output. -## Edit Existing MCP Server +### Virtual Server + +Use `servers[].enabled_tools` for each source server. Omit `enabled_tools` only when exposing every tool from that source. + +## Update Auth Use update-by-manifest: 1. Fetch the current MCP server config. -2. Convert it into the corresponding manifest shape. -3. Modify only the requested fields. -4. Preserve collaborators, auth settings, and existing server/tool lists unless the user asked to change them. -5. Show the diff and get confirmation. -6. Apply the full updated manifest. +2. Preserve name, URL/spec, selected tools, collaborators, TLS, tags, and unrelated settings. +3. Replace only the `auth_data` block requested by the user. +4. Use secret references for shared credentials. +5. Show the old auth mode and new auth mode. +6. Show YAML/diff, dry-run, and apply only after explicit confirmation. + +## Access Control + +Collaborators are part of MCP server creation and update. + +Use subject formats: + +- `user:` +- `team:` +- `serviceaccount:` +- `virtualaccount:` + +Default role for examples is `mcp-server-manager`. + +To list access: + +```bash +$TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID' +``` -Do not patch blindly from memory. +Adding collaborators is allowed with confirmation. Removing collaborators is dashboard-only. + +## Add To Client + +The gateway UI can generate client setup snippets for: + +- Cursor +- VS Code +- Claude Code +- Python +- TypeScript +- Windsurf +- Codex + +Use the `Add to Client` UI or the generated snippet from the dashboard. Do not click, reveal, paste, or print API keys unless the user explicitly asks to reveal them and understands the exposure. ## Apply +Always run the dry-run first: + ```bash tfy apply -f mcp-server.yaml --dry-run --show-diff -tfy apply -f mcp-server.yaml ``` -Run the final apply only after explicit user confirmation. +Run the final apply only after explicit user confirmation: + +```bash +tfy apply -f mcp-server.yaml +``` ## Delete @@ -183,10 +370,13 @@ To delete this MCP server, open the TrueFoundry dashboard, go to AI Gateway -> M - The user can list MCP servers. -- The user can add remote, virtual, OpenAPI, or hosted stdio-backed MCP servers. -- The user can update an existing MCP server through a reviewed full-manifest apply. -- Secrets are referenced with `tfy-secret://...`, never embedded. +- The user can create remote, official remote, virtual, OpenAPI, and hosted STDIO-backed MCP servers. +- Auth-disabled, API key, OAuth2, and token-passthrough configurations match the live gateway YAML shape. +- The user can enable or disable tools while preserving unrelated server config. +- The user can update auth and access control through reviewed full-manifest changes. +- Client attachment guidance covers Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, and Codex. +- Shared credentials use `tfy-secret://...` references or explicit user placeholders, never hidden raw secrets. - Final `tfy apply` is gated by a summary, YAML/diff, exact command, and explicit confirmation. -- Deletes are dashboard-only. +- Deletes and collaborator removals are dashboard-only. From 752d5b53cbf8bdec228e51a8931e0ae75fd3936a Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Tue, 19 May 2026 12:23:07 -0700 Subject: [PATCH 3/5] Add MCP Gateway UI references --- skills/mcp-servers/SKILL.md | 3 + .../references/mcp-gateway-ui-flows.md | 190 +++++++++++++++++ .../references/mcp-yaml-variations.md | 196 ++++++++++++++++++ 3 files changed, 389 insertions(+) create mode 100644 skills/mcp-servers/references/mcp-gateway-ui-flows.md create mode 100644 skills/mcp-servers/references/mcp-yaml-variations.md diff --git a/skills/mcp-servers/SKILL.md b/skills/mcp-servers/SKILL.md index 66baf92..3a2668d 100644 --- a/skills/mcp-servers/SKILL.md +++ b/skills/mcp-servers/SKILL.md @@ -49,6 +49,9 @@ Before every final `tfy apply`, always show: Then ask for explicit confirmation. Run only the dry-run before confirmation. +For detailed dashboard click paths, use [references/mcp-gateway-ui-flows.md](references/mcp-gateway-ui-flows.md). +For concrete manifest variants by server type and auth mode, use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md). + ## List MCP Servers Use the platform UI when available. For API fallback: diff --git a/skills/mcp-servers/references/mcp-gateway-ui-flows.md b/skills/mcp-servers/references/mcp-gateway-ui-flows.md new file mode 100644 index 0000000..19c83ab --- /dev/null +++ b/skills/mcp-servers/references/mcp-gateway-ui-flows.md @@ -0,0 +1,190 @@ +--- +description: UI navigation notes for TrueFoundry MCP Gateway server creation, editing, client attachment, and access control. +--- + +# MCP Gateway UI Flows + +Use this reference when operating or documenting the MCP Gateway dashboard. It captures observed UI paths from `AI Gateway -> MCP Gateway`. + +## Server List + +The MCP Gateway page shows server cards with: + +- server name +- description +- type, such as `Remote` or `Virtual` +- auth mode, such as `No Auth`, `OAuth2`, `Header Auth`, or `Chained` +- primary action, such as `Add to Client` or `Authenticate` + +The small action button on each card opens: + +- `Edit` +- `Access Control` +- `Delete` + +Do not use `Delete` from an agent. Delete remains dashboard-only manual work. + +## Add Server Chooser + +Click `Add Server` to open `Add new MCP Server`. + +Observed creation options: + +- `Connect Official Remote MCP Servers` +- `Connect any Remote MCP Server` +- `Create a Virtual MCP Server` +- `Create a Hosted STDIO-based MCP Server` +- `Import from OpenAPI Spec` + +## Connect Any Remote MCP Server + +Path: `Add Server` -> `Connect any Remote MCP Server`. + +Base fields: + +- `Name` +- `Description` +- `URL` +- `Collaborators` +- optional `Auth Data` +- `Show advanced fields` +- `Apply using YAML` +- `Add MCP Server` + +Default collaborator observed: + +- subject: current user +- displayed role: `MCP Server Manager` +- YAML role id: `mcp-server-manager` + +Use `Apply using YAML` to inspect the manifest before creating or updating. Do not click `Add MCP Server` until the user has explicitly approved the final apply/create action. + +## Remote MCP Auth Controls + +`Auth Data` is optional. Toggle it on to choose: + +- `API Key` +- `OAuth2` +- `Token Passthrough` + +### API Key + +API key mode is for static headers. + +Configuration options: + +- `Shared Credentials`: one key used by everyone. +- `Individual Credentials`: each user provides their own key. +- `Headers`: one or more header key/value pairs. + +For shared credentials, prefer `tfy-secret://...` references. For individual credentials, use placeholders such as `Bearer {{API_KEY}}`. + +### OAuth2 + +OAuth2 mode is for temporary access tokens from a third-party login or server-to-server auth. + +Grant types: + +- `Authorization Code`: user-facing sign-in flow. +- `Client Credentials`: server-to-server flow with shared client credentials. + +Authorization Code fields observed: + +- `Authorization URL` +- `Token URL` +- `Client ID` +- `Client Secret` +- `Registration URL (Used for Dynamic Client Registration)` +- `Code Challenge Methods Supported` +- `JWT Source` +- `Scopes` +- `Additional Token Parameters` + +Client Credentials fields observed: + +- `Token URL` +- `Client ID` +- `Client Secret` +- `JWT Source` +- `Scopes` +- `Additional Token Parameters` + +### Token Passthrough + +Token passthrough forwards the user's existing TrueFoundry auth token to the MCP server. No extra fields were shown. + +## Create Virtual MCP Server + +Path: `Add Server` -> `Create a Virtual MCP Server`. + +Fields: + +- `Name` +- `Description` +- `Collaborators` +- `Source MCP Servers` +- optional `Override authentication header` +- `Selected Tools` +- `Show advanced fields` +- `Apply using YAML` +- `Create Virtual MCP` + +Observed behavior: + +- Source servers can be selected from existing MCP servers. +- Tools can be selected from each source server. +- Edit screen can show available tools and `Enable All Tools`. +- Use `servers[].enabled_tools` in YAML for selected subsets. +- Omit `enabled_tools` only when exposing every tool from that source server. + +## Create Hosted STDIO MCP Server + +Path: `Add Server` -> `Create a Hosted STDIO-based MCP Server`. + +Fields: + +- `STDIO Configuration (JSON)` +- `Upload JSON file` +- `Import Manifest` + +Input is a local-style `mcpServers` JSON object with `command`, `args`, and optional `env`. + +Move real environment credentials to secret references or ask the user to manage them securely; do not preserve raw secrets in chat. + +## Import From OpenAPI Spec + +Path: `Add Server` -> `Import from OpenAPI Spec`. + +Fields observed: + +- `Import OpenAPI Spec` +- `Build via URL` +- `Paste Spec` +- `OpenAPI Spec URL` +- `Import Tools` +- `Continue to Next Step` + +Use trusted spec URLs only. Prefer pasted/inline specs for sensitive private APIs. + +## Add To Client + +`Add to Client` opens a `How to use` modal. + +Client tabs observed: + +- Cursor +- VS Code +- Claude Code +- Python +- TypeScript +- Windsurf +- Codex + +The modal includes: + +- client config snippet +- `Copy` +- `Show API Key` + +Do not click, reveal, print, or paste API keys unless the user explicitly asks and accepts exposure. + diff --git a/skills/mcp-servers/references/mcp-yaml-variations.md b/skills/mcp-servers/references/mcp-yaml-variations.md new file mode 100644 index 0000000..a04e668 --- /dev/null +++ b/skills/mcp-servers/references/mcp-yaml-variations.md @@ -0,0 +1,196 @@ +--- +description: YAML examples for TrueFoundry MCP Gateway server types and auth variations observed from the live UI. +--- + +# MCP Gateway YAML Variations + +Use these examples when generating or reviewing MCP Gateway manifests. Treat the live dashboard `Apply using YAML` preview as the final source of truth if it differs. + +Security and trust policy: only use remote MCP URLs and OpenAPI spec URLs that the user explicitly confirms are trusted. Treat unknown remote URLs as untrusted, and do not run, import, or apply them without confirmation. + +## Remote MCP With No Auth + +Auth disabled means omit `auth_data`. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +``` + +## Remote MCP With Shared API Key + +Use shared API key auth when one credential is used for all callers. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: header + auth_level: global + headers: + Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" +``` + +## Remote MCP With Per-User API Key + +Use per-user API key auth when each user supplies their own value. + +```yaml +name: analytics-mcp +description: Analytics tools for internal workflows +url: https://analytics.example.com/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: header + auth_level: per_user + headers: + Authorization: "Bearer {{API_KEY}}" +``` + +## Remote MCP With OAuth2 Authorization Code + +Use authorization code for user-facing third-party sign-in. + +```yaml +name: linear-mcp +description: Linear project management tools +url: https://mcp.linear.app/mcp +collaborators: + - subject: user:alice@example.com + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: oauth2 + grant_type: authorization_code + authorization_url: https://mcp.linear.app/authorize + token_url: https://mcp.linear.app/token + client_id: tfy-secret://tenant:mcp-secrets:linear-client-id + client_secret: tfy-secret://tenant:mcp-secrets:linear-client-secret + registration_url: https://mcp.linear.app/register + jwt_source: access_token +``` + +## Remote MCP With OAuth2 Client Credentials + +Use client credentials for server-to-server OAuth. + +```yaml +name: service-mcp +description: Service-to-service MCP tools +url: https://service.example.com/mcp +collaborators: + - subject: team:platform + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: oauth2 + grant_type: client_credentials + token_url: https://auth.example.com/token + client_id: tfy-secret://tenant:mcp-secrets:service-client-id + client_secret: tfy-secret://tenant:mcp-secrets:service-client-secret + jwt_source: access_token +``` + +## Remote MCP With Token Passthrough + +Use passthrough when the downstream MCP server should receive the caller's existing TrueFoundry auth token. + +```yaml +name: passthrough-mcp +description: MCP server using caller identity +url: https://service.example.com/mcp +collaborators: + - subject: team:platform + role_id: mcp-server-manager +type: mcp-server/remote +auth_data: + type: passthrough +``` + +## Virtual MCP With Selected Tools + +Use `enabled_tools` to expose a subset from each source server. + +```yaml +name: dev-tools +description: Composite server for engineering workflows +type: mcp-server/virtual +servers: + - name: linear + enabled_tools: + - list_issues + - create_issue + - name: deepwiki + enabled_tools: + - read_wiki_structure + - read_wiki_contents +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## Virtual MCP Exposing All Tools From A Source + +Omit `enabled_tools` only for sources where every tool should be exposed. + +```yaml +name: broad-dev-tools +description: Composite server exposing all DeepWiki tools and selected Linear tools +type: mcp-server/virtual +servers: + - name: deepwiki + - name: linear + enabled_tools: + - list_issues + - create_issue +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## OpenAPI MCP From Remote Spec + +```yaml +name: internal-api +description: Internal API exposed as MCP tools +type: mcp-server/openapi +spec: + type: remote + url: https://internal.example.com/openapi.json +collaborators: + - subject: team:platform + role_id: mcp-server-manager +``` + +## Hosted STDIO Input Shape + +Hosted STDIO creation starts from an `mcpServers` JSON config. Use the gateway YAML preview as the manifest source after import. + +```json +{ + "mcpServers": { + "exa-user1": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], + "env": { + "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" + } + } + } +} +``` + +Do not leave real env secrets in the JSON when sharing it in chat or committing examples. From 9fec6c94c8653a6aec416f342099701d262d9f8b Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Tue, 19 May 2026 13:14:17 -0700 Subject: [PATCH 4/5] Slim MCP Gateway skill references --- .../gateway/references/schemas/mcp-server.md | 330 ++++-------------- skills/mcp-servers/SKILL.md | 318 +++++------------ .../references/mcp-gateway-ui-flows.md | 12 +- .../references/mcp-yaml-variations.md | 13 + 4 files changed, 192 insertions(+), 481 deletions(-) diff --git a/skills/gateway/references/schemas/mcp-server.md b/skills/gateway/references/schemas/mcp-server.md index d84bba4..af2bdd2 100644 --- a/skills/gateway/references/schemas/mcp-server.md +++ b/skills/gateway/references/schemas/mcp-server.md @@ -1,11 +1,18 @@ --- name: mcp-server-schema -description: Schema reference for MCP server manifests -- remote, OpenAPI, virtual, and hosted STDIO-derived servers -- including auth, access control, and tool filtering workflows. +description: Compact schema reference for MCP Gateway manifests. For full YAML examples, use the MCP servers skill references. --- # MCP Server Schema Reference -MCP Gateway manages remote endpoints, OpenAPI-backed servers, virtual composite servers, and hosted STDIO-derived servers. Use the live gateway YAML preview as the source of truth when it exposes fields not covered here. +This file is a compact schema index for gateway-related work. The canonical MCP Gateway workflow lives in `skills/mcp-servers/SKILL.md`. + +For detailed examples, read: + +- `../../../mcp-servers/references/mcp-yaml-variations.md` +- `../../../mcp-servers/references/mcp-gateway-ui-flows.md` + +Treat the live dashboard `Apply using YAML` preview as the source of truth when it differs from static examples. ## Fetch Existing Config @@ -19,281 +26,101 @@ $TFY_API_SH GET /api/svc/v1/mcp-servers/SERVER_ID ## Common Fields -| Field | Type | Required | Description | -|-------|------|----------|-------------| +| Field | Type | Required | Notes | +|-------|------|----------|-------| | `name` | string | Yes | Unique MCP server name | | `type` | string | Yes | `mcp-server/remote`, `mcp-server/openapi`, or `mcp-server/virtual` | | `description` | string | Yes | Human-readable purpose | -| `collaborators` | array | Yes | Access grants for users, teams, service accounts, or virtual accounts | -| `tags` | string[] | No | Tags for organization and filtering | - -### Collaborator Entry - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `subject` | string | Yes | `user:`, `team:`, `serviceaccount:`, or `virtualaccount:` | -| `role_id` | string | Yes | Use `mcp-server-manager` for management access unless another MCP server role is requested | - -```yaml -collaborators: - - subject: user:alice@example.com - role_id: mcp-server-manager -``` - -## Remote MCP Server - -Connects to an existing HTTP MCP endpoint. - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `mcp-server/remote` | -| `description` | string | Yes | Human-readable purpose | -| `url` | string | Yes | MCP endpoint URL | -| `auth_data` | object | No | Omit when auth is disabled | | `collaborators` | array | Yes | Access grants | -| `tls_settings` | object | No | TLS settings | -| `tags` | string[] | No | Tags | - -Auth disabled: - -```yaml -name: analytics-mcp -description: Analytics tools for internal workflows -url: https://analytics.example.com/mcp -collaborators: - - subject: user:alice@example.com - role_id: mcp-server-manager -type: mcp-server/remote -``` - -## Auth Data - -### API Key / Header Auth - -Use `type: header` when the downstream MCP server expects one or more request headers. +| `tags` | string[] | No | Organization/filtering metadata | -Shared credentials: - -```yaml -auth_data: - type: header - auth_level: global - headers: - Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" -``` - -Individual credentials: - -```yaml -auth_data: - type: header - auth_level: per_user - headers: - Authorization: "Bearer {{API_KEY}}" -``` +Collaborator subjects: -Rules: +- `user:` +- `team:` +- `serviceaccount:` +- `virtualaccount:` -- `auth_level: global` means one shared credential is used for all callers. -- `auth_level: per_user` means each user supplies their own credential. -- Use `tfy-secret://...` references for shared real credentials. -- Use placeholders such as `{{API_KEY}}` for per-user values. +Use `role_id: mcp-server-manager` for management access unless the user requests another role. -### OAuth2 Authorization Code +## Server Types -Use for user-facing OAuth login flows. +### Remote -```yaml -auth_data: - type: oauth2 - grant_type: authorization_code - authorization_url: https://auth.example.com/authorize - token_url: https://auth.example.com/token - client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id - client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret - registration_url: https://auth.example.com/register - jwt_source: access_token -``` +Connects to an existing HTTP MCP endpoint. -Notes: +Required fields: -- `token_url` and `jwt_source` are required in the UI. -- `authorization_url`, `client_id`, `client_secret`, and `registration_url` may be optional depending on the provider and DCR support. -- Optional settings may include scopes, PKCE/code challenge methods, and additional token parameters. +- `name` +- `description` +- `type: mcp-server/remote` +- `url` +- `collaborators` -### OAuth2 Client Credentials +Optional fields include `auth_data`, `tls_settings`, and `tags`. -Use for server-to-server OAuth. +### OpenAPI -```yaml -auth_data: - type: oauth2 - grant_type: client_credentials - token_url: https://auth.example.com/token - client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id - client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret - jwt_source: access_token -``` +Wraps OpenAPI operations as MCP tools. -Notes: +Required fields: -- `token_url`, `client_id`, `client_secret`, and `jwt_source` are required in the UI. -- Optional settings may include scopes and additional token parameters. +- `name` +- `description` +- `type: mcp-server/openapi` +- `spec` +- `collaborators` -### Token Passthrough +Use only trusted remote spec URLs. Prefer inline specs for sensitive private APIs. -Use when the downstream MCP server should receive the caller's existing TrueFoundry auth token. +### Virtual -```yaml -auth_data: - type: passthrough -``` +Composes existing MCP servers into one virtual server. -## TLS Settings +Required fields: -```yaml -tls_settings: - ca_cert: tfy-secret://tenant:mcp-secrets:ca-cert-pem - insecure_skip_verify: false -``` +- `name` +- `description` +- `type: mcp-server/virtual` +- `servers` +- `collaborators` -Use a secret reference for CA certificate PEM data. Keep `insecure_skip_verify: false` unless the user explicitly accepts the risk. +Each `servers[]` entry needs `name`. Add `enabled_tools` only when exposing a selected subset. Omit `enabled_tools` when exposing every tool from that source. -## OpenAPI MCP Server +### Hosted STDIO-Derived -Wraps an OpenAPI specification as MCP tools. Operations in the spec become tools. +The UI starts from an `mcpServers` JSON object with `command`, `args`, and optional `env`, then generates the gateway manifest. Use the generated YAML preview as the manifest source of truth. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique server name | -| `type` | string | Yes | `mcp-server/openapi` | -| `description` | string | Yes | Human-readable purpose | -| `spec` | object | Yes | Remote or inline OpenAPI spec | -| `auth_data` | object | No | Same auth options as remote server | -| `collaborators` | array | Yes | Access grants | - -Remote spec: - -```yaml -name: internal-api -description: Internal API exposed as MCP tools -type: mcp-server/openapi -spec: - type: remote - url: https://internal.example.com/openapi.json -collaborators: - - subject: team:platform - role_id: mcp-server-manager -``` - -Inline spec: - -```yaml -spec: - type: inline - content: | - openapi: "3.0.0" - info: - title: Internal API - version: "1.0" - paths: - /health: - get: - operationId: healthCheck - responses: - "200": - description: OK -``` - -Only use trusted remote spec URLs. Prefer inline specs for sensitive private APIs. - -## Virtual MCP Server +## Auth Data -Composes existing MCP servers into one virtual server. Each source can expose all tools or a selected subset. +No auth means omit `auth_data`. -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Unique virtual server name | -| `type` | string | Yes | `mcp-server/virtual` | -| `description` | string | Yes | Human-readable purpose | -| `servers` | array | Yes | Source server entries | -| `collaborators` | array | Yes | Access grants | +Supported auth modes: -Source server entry: - -| Field | Type | Required | Description | -|-------|------|----------|-------------| -| `name` | string | Yes | Name of an already registered MCP server | -| `enabled_tools` | string[] | No | Subset of tools to expose; omit to expose every tool from that source | - -```yaml -name: dev-tools -description: Composite server for engineering workflows -type: mcp-server/virtual -servers: - - name: linear - enabled_tools: - - list_issues - - create_issue - - name: deepwiki - enabled_tools: - - read_wiki_structure - - read_wiki_contents -collaborators: - - subject: team:platform - role_id: mcp-server-manager -``` +| UI mode | YAML shape | +|---------|------------| +| API Key / shared credentials | `auth_data.type: header`, `auth_level: global`, `headers` | +| API Key / individual credentials | `auth_data.type: header`, `auth_level: per_user`, `headers` with placeholders | +| OAuth2 authorization code | `auth_data.type: oauth2`, `grant_type: authorization_code` | +| OAuth2 client credentials | `auth_data.type: oauth2`, `grant_type: client_credentials` | +| Token passthrough | `auth_data.type: passthrough` | -Creation flow: - -1. Choose `name` and `description`. -2. Select source MCP servers. -3. Enumerate available tools for each source. -4. Include `enabled_tools` only for selected subsets. -5. Add collaborators. -6. Dry-run and apply only after explicit confirmation. - -## Hosted STDIO-Derived Server - -The UI accepts a local-style `mcpServers` JSON config and turns it into a gateway-hosted/exposed MCP server. - -Input shape: - -```json -{ - "mcpServers": { - "exa-user1": { - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], - "env": { - "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" - } - } - } -} -``` +Use `tfy-secret://...` references for shared real credentials. Use placeholders such as `{{API_KEY}}` for per-user values. -Use the generated gateway YAML preview as the manifest source of truth. Move real env secrets into secret references wherever supported. +Read `../../../mcp-servers/references/mcp-yaml-variations.md` for concrete auth examples. ## Tool Enablement -### Normal Remote/OpenAPI Servers - -The gateway UI supports enabling and disabling tools on normal remote/OpenAPI servers. When changing tool exposure for an existing non-virtual server: +For normal remote/OpenAPI servers: -1. Fetch the server by ID. -2. Inspect the API response or UI YAML preview for the existing tool-selection shape. +1. Fetch the current server config. +2. Inspect the API response or UI YAML preview for the tool-selection shape. 3. Modify only the requested tool-selection fields. 4. Preserve URL/spec, auth, TLS, collaborators, tags, and unrelated fields. -5. Dry-run with `tfy apply -f mcp-server.yaml --dry-run --show-diff`. -6. Apply only after explicit confirmation. Do not guess field names for normal-server tool filtering. -### Virtual Servers - -Use `servers[].enabled_tools`. Omit it only when exposing all tools from a source server. +For virtual servers, use `servers[].enabled_tools`. ## Generate And Validate @@ -309,23 +136,12 @@ Apply only after explicit confirmation: tfy apply -f mcp-server.yaml ``` -Common issues: - -- Server `name` is not unique. -- Raw credentials are embedded instead of secret references or per-user placeholders. -- OAuth2 grant type does not match required fields. -- OpenAPI spec URL is untrusted or produces too many tools. -- Virtual server references unknown source server names. -- `enabled_tools` includes names that do not exist on the source server. -- YAML preview and hand-written manifest disagree; prefer the gateway preview. - -## Checklist - -- [ ] `name`, `description`, `type`, and collaborators are set. -- [ ] Auth disabled means `auth_data` is omitted. -- [ ] API key auth includes `type: header`, `auth_level`, and headers. -- [ ] OAuth2 auth includes `grant_type`, `token_url`, and `jwt_source`. -- [ ] Shared secrets use `tfy-secret://...`. -- [ ] Virtual server sources and `enabled_tools` are valid. -- [ ] Access grants use MCP server roles such as `mcp-server-manager`. -- [ ] Dry-run passes before any final apply. +Common checks: + +- `name`, `description`, `type`, and collaborators are set. +- Auth disabled omits `auth_data`. +- API key auth includes `type: header`, `auth_level`, and headers. +- OAuth2 auth includes the right `grant_type`, `token_url`, and `jwt_source`. +- Shared secrets use `tfy-secret://...`. +- Virtual source servers and `enabled_tools` are valid. +- YAML preview and hand-written manifest agree; prefer the gateway preview. diff --git a/skills/mcp-servers/SKILL.md b/skills/mcp-servers/SKILL.md index 3a2668d..3151761 100644 --- a/skills/mcp-servers/SKILL.md +++ b/skills/mcp-servers/SKILL.md @@ -14,291 +14,178 @@ Manage MCP servers in TrueFoundry AI Gateway. Use this skill when the user wants to: -- List registered MCP servers. -- Connect any remote MCP server by URL. -- Connect an official remote MCP server from the gateway catalog. -- Create a virtual MCP server from selected tools across multiple MCP servers. -- Create a hosted STDIO MCP server from an `mcpServers` JSON config. -- Import an OpenAPI spec as an MCP server. -- Enable or disable tools on normal remote/OpenAPI servers or virtual server source entries. -- Update MCP server auth, access, metadata, endpoint/spec, or selected tools. -- Add an MCP server to clients such as Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, or Codex. +- List MCP servers attached to a gateway. +- Connect remote or official remote MCP servers. +- Create virtual MCP servers from tools across multiple source servers. +- Create hosted STDIO MCP servers from `mcpServers` JSON. +- Import OpenAPI specs as MCP servers. +- Enable or disable tools. +- Update auth, access, metadata, endpoint/spec, or selected tools. +- Add MCP servers to clients such as Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, or Codex. -Do not manage raw secrets here. Use `tfy-secret://...` references or route secret creation to the `platform` skill. - -Do not delete MCP servers from the agent. If deletion is requested, direct the user to the TrueFoundry dashboard. +Do not delete MCP servers or remove collaborators from the agent. Route those requests to the TrueFoundry dashboard. -## Preflight +## Reference Map + +Load only the reference needed for the user's task: + +| Task | Reference | +|------|-----------| +| Browser/UI operation, click paths, form fields, add-to-client modal | [references/mcp-gateway-ui-flows.md](references/mcp-gateway-ui-flows.md) | +| YAML examples for auth modes, server types, virtual tool selection, OpenAPI, hosted STDIO | [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) | + +Treat the live dashboard `Apply using YAML` preview as the source of truth when it differs from examples. -1. Verify `tfy login` is complete. If not, use `truefoundry-onboard`. -2. Verify the target tenant from `TFY_BASE_URL`/`TFY_HOST`. -3. Confirm the workspace or registry scope with the user before applying changes. -4. Use `mcp-server-manager` as the default role when granting MCP server management access unless the user requests another role. -5. Use `tfy-secret://...` references for shared credentials whenever possible; never inline real credentials in chat. +## Safety Rules -Before every final `tfy apply`, always show: +- Verify `tfy login` is complete. If not, use `truefoundry-onboard`. +- Verify the target tenant from `TFY_BASE_URL`/`TFY_HOST`. +- Confirm the workspace or registry scope with the user before applying changes. +- Use `mcp-server-manager` as the default role unless the user requests another role. +- Use collaborator subjects as `user:`, `team:`, `serviceaccount:`, or `virtualaccount:`. +- Use `tfy-secret://...` references for shared credentials whenever possible. +- Never print, paste, or reveal real credentials unless the user explicitly asks and accepts exposure. +- Do not call DELETE APIs, destructive CLI commands, or collaborator-removal flows. + +Before every final `tfy apply`, show: - Plain-English summary of the change. - Target tenant and workspace/scope. - Full YAML or diff. - Exact command to be run. -Then ask for explicit confirmation. Run only the dry-run before confirmation. - -For detailed dashboard click paths, use [references/mcp-gateway-ui-flows.md](references/mcp-gateway-ui-flows.md). -For concrete manifest variants by server type and auth mode, use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md). +Then ask for explicit confirmation. Run only dry-runs before confirmation. ## List MCP Servers -Use the platform UI when available. For API fallback: +Prefer the dashboard when the user is working in the UI. For API fallback: ```bash TFY_API_SH=~/.claude/skills/truefoundry-mcp-servers/scripts/tfy-api.sh $TFY_API_SH GET /api/svc/v1/mcp-servers ``` -Present: +Present servers as: ```text MCP Servers | Name | Type | Auth | ID | URL / Source | ``` -## Connect Any Remote MCP Server +## Connect Remote MCP Server -Use this for an already deployed HTTP MCP endpoint. +Use this for an existing HTTP MCP endpoint. -Required inputs: +Collect: - `name` - `description` - `url` -- collaborators: `user:` or `team:` with role, default `mcp-server-manager` +- collaborators and roles - auth enabled or disabled +- if auth is enabled: API key/header, OAuth2, or token passthrough -If auth is disabled, omit `auth_data`. - -```yaml -name: analytics-mcp -description: Analytics tools for internal workflows -url: https://analytics.example.com/mcp -collaborators: - - subject: user:alice@example.com - role_id: mcp-server-manager -type: mcp-server/remote -``` - -### API Key Auth - -Use this when the downstream MCP server expects static request headers. - -Ask whether credentials are: - -- Shared credentials: one key used by everyone; prefer a `tfy-secret://...` reference. -- Individual credentials: each user supplies their own key; use a placeholder such as `Bearer {{API_KEY}}`. +Auth rules: -```yaml -auth_data: - type: header - auth_level: global - headers: - Authorization: "Bearer tfy-secret://tenant:mcp-secrets:analytics-token" -``` - -For individual credentials: - -```yaml -auth_data: - type: header - auth_level: per_user - headers: - Authorization: "Bearer {{API_KEY}}" -``` - -### OAuth2 Auth - -Use this when users or a server-to-server client should obtain temporary access tokens from an OAuth provider. - -Authorization code is for user-facing sign-in: - -```yaml -auth_data: - type: oauth2 - grant_type: authorization_code - authorization_url: https://auth.example.com/authorize - token_url: https://auth.example.com/token - client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id - client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret - registration_url: https://auth.example.com/register - jwt_source: access_token -``` - -Client credentials is for server-to-server auth: - -```yaml -auth_data: - type: oauth2 - grant_type: client_credentials - token_url: https://auth.example.com/token - client_id: tfy-secret://tenant:mcp-secrets:oauth-client-id - client_secret: tfy-secret://tenant:mcp-secrets:oauth-client-secret - jwt_source: access_token -``` +- No auth: omit `auth_data`. +- API key/header auth: support shared credentials and individual credentials; require at least one header. +- OAuth2: support authorization code and client credentials; include optional scopes, PKCE/code challenge methods, Dynamic Client Registration URL, and additional token params only when supplied or shown by the UI preview. +- Token passthrough: use the caller's existing TrueFoundry token; no extra fields are needed. -Optional OAuth2 fields may include scopes, PKCE/code challenge methods, registration URL for Dynamic Client Registration, and additional token parameters. Use the gateway YAML preview or fetched config as the source of truth for exact optional field names. - -### Token Passthrough - -Use this when the downstream MCP server should receive the caller's existing TrueFoundry auth token. - -```yaml -auth_data: - type: passthrough -``` +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for concrete YAML shapes. ## Connect Official Remote MCP Server -Use this when the user wants a built-in catalog server such as GitHub, Linear, Sentry, Atlassian, Figma, Slack, Notion, Stripe, HuggingFace, or similar. +Use this for catalog servers such as GitHub, Linear, Sentry, Atlassian, Figma, Slack, Notion, Stripe, HuggingFace, or similar. Flow: -1. Identify the official server from the gateway catalog. -2. Confirm the catalog auth mode: no auth, OAuth2, or header auth. -3. For OAuth2, prepare the server config and tell the user they may need to complete the browser authentication flow after creation. -4. For header auth, collect the header names and use secret references or per-user placeholders. +1. Identify the official server in the gateway catalog. +2. Confirm the catalog auth mode. +3. For OAuth2, tell the user they may need to complete a browser authentication flow after creation. +4. For header auth, collect header names and use secret references or per-user placeholders. 5. Confirm collaborators. -6. Generate YAML or use the UI's `Apply using YAML` output. -7. Dry-run, show diff, then apply only after explicit confirmation. +6. Generate YAML from the UI preview or the YAML reference. +7. Dry-run, show diff, then apply only after confirmation. ## Create Virtual MCP Server Use this to expose selected tools from multiple existing MCP servers through one virtual MCP server. -Required inputs: +Collect: - virtual MCP `name` - `description` -- source MCP servers to include +- source MCP servers - tools to expose from each source server - collaborators and roles -- optional source-server auth header override, if the gateway requires it +- optional source-server auth header override if the gateway requires it Flow: 1. List registered MCP servers. -2. Select multiple source MCP servers. -3. For each source server, enumerate available tools from the gateway UI/API. +2. Select source MCP servers. +3. Enumerate available tools for each source server. 4. Ask which tools to expose from each source. -5. Omit `enabled_tools` for a source server only when exposing all tools from that server. -6. Add collaborators with `mcp-server-manager` unless the user requests a different role. -7. Show a plain-English summary with virtual server name, source servers, selected tools, and access. -8. Show the full YAML. -9. Run `tfy apply -f mcp-server.yaml --dry-run --show-diff`. -10. Run the final apply only after explicit confirmation. - -```yaml -name: dev-tools -description: Composite server for engineering workflows -type: mcp-server/virtual -servers: - - name: linear - enabled_tools: - - list_issues - - create_issue - - name: deepwiki - enabled_tools: - - read_wiki_structure - - read_wiki_contents -collaborators: - - subject: team:platform - role_id: mcp-server-manager -``` +5. Use `servers[].enabled_tools` for selected subsets. +6. Omit `enabled_tools` for a source only when exposing every tool from that source. +7. Add collaborators with `mcp-server-manager` unless requested otherwise. +8. Show virtual server name, source servers, selected tools, and access. +9. Show YAML, dry-run, and apply only after confirmation. + +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for virtual server YAML examples. ## Create Hosted STDIO MCP Server Use this when the user has a local-style MCP config and wants the gateway to host/expose it. -Required input: - -- JSON containing an `mcpServers` object. - -Example input: - -```json -{ - "mcpServers": { - "exa-user1": { - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"], - "env": { - "EXA_API_KEY": "REPLACE_WITH_EXA_API_KEY" - } - } - } -} -``` +Collect JSON containing an `mcpServers` object with server `command`, `args`, and optional `env`. Flow: -1. Ask the user for the STDIO config or JSON file. -2. Replace raw environment secrets with secret references where the gateway supports it, or tell the user exactly which values must be moved to secrets. -3. Use the gateway import flow or YAML preview as the source of truth for the generated manifest. +1. Ask for the STDIO JSON or file. +2. Replace raw environment secrets with secret references where supported, or tell the user which values must be moved to secrets. +3. Use the gateway import flow or YAML preview as the source of truth for the manifest generated after import. 4. Show summary, YAML/diff, dry-run, and confirmation-gated apply. +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for the input shape. + ## Import From OpenAPI Spec Use this to expose OpenAPI operations as MCP tools. -Required inputs: +Collect: - `name` - `description` -- OpenAPI spec source: remote URL or pasted inline spec +- OpenAPI spec source: trusted remote URL or pasted inline spec - selected tools/operations - collaborators -- optional auth using the same auth modes as remote MCP servers - -For remote specs, confirm the URL is trusted before use. - -```yaml -name: internal-api -description: Internal API exposed as MCP tools -type: mcp-server/openapi -spec: - type: remote - url: https://internal.example.com/openapi.json -collaborators: - - subject: team:platform - role_id: mcp-server-manager -``` +- optional auth using the same modes as remote MCP servers -## Enable Or Disable Tools - -Tool filtering is supported for both normal MCP servers and virtual MCP servers. +For remote specs, confirm the URL is trusted before use. Prefer pasted/inline specs for sensitive private APIs. -### Normal Remote/OpenAPI Server +## Enable Or Disable Tools -Use this when the user wants to enable or disable tools exposed by a single non-virtual MCP server. +Tool filtering is supported for normal remote/OpenAPI servers and virtual MCP servers. -Flow: +For normal remote/OpenAPI servers: 1. Fetch the current MCP server config by ID. -2. Inspect the returned config or UI YAML preview for the existing tool-selection fields. -3. Fetch or confirm the available tool names from the gateway UI/API. -4. Modify only the explicit tool-selection fields requested by the user. +2. Inspect the API response or UI YAML preview for the existing tool-selection shape. +3. Fetch or confirm available tool names. +4. Modify only the requested tool-selection fields. 5. Preserve name, URL/spec, auth, collaborators, TLS, tags, and unrelated settings. 6. Show the before/after tool list or YAML diff. -7. Dry-run and apply only after explicit confirmation. - -Do not invent field names for normal-server tool filtering. If the API response does not expose the tool-selection shape, direct the user to the dashboard MCP server edit screen or ask them to provide the `Apply using YAML` output. +7. Dry-run and apply only after confirmation. -### Virtual Server +Do not invent field names for normal-server tool filtering. If the API response does not expose the shape, use the dashboard edit screen or ask the user for the `Apply using YAML` output. -Use `servers[].enabled_tools` for each source server. Omit `enabled_tools` only when exposing every tool from that source. +For virtual servers, use `servers[].enabled_tools`; omit it only when exposing every tool from that source. ## Update Auth @@ -306,23 +193,16 @@ Use update-by-manifest: 1. Fetch the current MCP server config. 2. Preserve name, URL/spec, selected tools, collaborators, TLS, tags, and unrelated settings. -3. Replace only the `auth_data` block requested by the user. +3. Replace only the requested `auth_data` block. 4. Use secret references for shared credentials. -5. Show the old auth mode and new auth mode. -6. Show YAML/diff, dry-run, and apply only after explicit confirmation. - -## Access Control - -Collaborators are part of MCP server creation and update. +5. Show old auth mode and new auth mode. +6. Show YAML/diff, dry-run, and apply only after confirmation. -Use subject formats: +Use [references/mcp-yaml-variations.md](references/mcp-yaml-variations.md) for auth examples. -- `user:` -- `team:` -- `serviceaccount:` -- `virtualaccount:` +## Access Control -Default role for examples is `mcp-server-manager`. +Adding collaborators is allowed with confirmation. Removing collaborators is dashboard-only. To list access: @@ -330,21 +210,13 @@ To list access: $TFY_API_SH GET '/api/svc/v1/collaborators?resourceType=mcp-server&resourceId=RESOURCE_ID' ``` -Adding collaborators is allowed with confirmation. Removing collaborators is dashboard-only. +When changing access, show the before/after collaborator list and preserve unrelated server config. ## Add To Client -The gateway UI can generate client setup snippets for: - -- Cursor -- VS Code -- Claude Code -- Python -- TypeScript -- Windsurf -- Codex +The gateway UI can generate setup snippets for Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, and Codex. -Use the `Add to Client` UI or the generated snippet from the dashboard. Do not click, reveal, paste, or print API keys unless the user explicitly asks to reveal them and understands the exposure. +Use the dashboard `Add to Client` modal or the generated snippet. Do not click, reveal, paste, or print API keys unless the user explicitly asks and understands the exposure. ## Apply @@ -375,11 +247,11 @@ To delete this MCP server, open the TrueFoundry dashboard, go to AI Gateway -> M - The user can list MCP servers. - The user can create remote, official remote, virtual, OpenAPI, and hosted STDIO-backed MCP servers. - Auth-disabled, API key, OAuth2, and token-passthrough configurations match the live gateway YAML shape. -- The user can enable or disable tools while preserving unrelated server config. -- The user can update auth and access control through reviewed full-manifest changes. +- Tool enable/disable updates preserve unrelated server config. +- Auth and access changes use reviewed full-manifest updates. - Client attachment guidance covers Cursor, VS Code, Claude Code, Python, TypeScript, Windsurf, and Codex. -- Shared credentials use `tfy-secret://...` references or explicit user placeholders, never hidden raw secrets. -- Final `tfy apply` is gated by a summary, YAML/diff, exact command, and explicit confirmation. +- Shared credentials use `tfy-secret://...` references or explicit placeholders. +- Final `tfy apply` is gated by summary, YAML/diff, exact command, and explicit confirmation. - Deletes and collaborator removals are dashboard-only. diff --git a/skills/mcp-servers/references/mcp-gateway-ui-flows.md b/skills/mcp-servers/references/mcp-gateway-ui-flows.md index 19c83ab..46164c9 100644 --- a/skills/mcp-servers/references/mcp-gateway-ui-flows.md +++ b/skills/mcp-servers/references/mcp-gateway-ui-flows.md @@ -6,6 +6,17 @@ description: UI navigation notes for TrueFoundry MCP Gateway server creation, ed Use this reference when operating or documenting the MCP Gateway dashboard. It captures observed UI paths from `AI Gateway -> MCP Gateway`. +## Contents + +- Server List +- Add Server Chooser +- Connect Any Remote MCP Server +- Remote MCP Auth Controls +- Create Virtual MCP Server +- Create Hosted STDIO MCP Server +- Import From OpenAPI Spec +- Add To Client + ## Server List The MCP Gateway page shows server cards with: @@ -187,4 +198,3 @@ The modal includes: - `Show API Key` Do not click, reveal, print, or paste API keys unless the user explicitly asks and accepts exposure. - diff --git a/skills/mcp-servers/references/mcp-yaml-variations.md b/skills/mcp-servers/references/mcp-yaml-variations.md index a04e668..b00d8f2 100644 --- a/skills/mcp-servers/references/mcp-yaml-variations.md +++ b/skills/mcp-servers/references/mcp-yaml-variations.md @@ -8,6 +8,19 @@ Use these examples when generating or reviewing MCP Gateway manifests. Treat the Security and trust policy: only use remote MCP URLs and OpenAPI spec URLs that the user explicitly confirms are trusted. Treat unknown remote URLs as untrusted, and do not run, import, or apply them without confirmation. +## Contents + +- Remote MCP With No Auth +- Remote MCP With Shared API Key +- Remote MCP With Per-User API Key +- Remote MCP With OAuth2 Authorization Code +- Remote MCP With OAuth2 Client Credentials +- Remote MCP With Token Passthrough +- Virtual MCP With Selected Tools +- Virtual MCP Exposing All Tools From A Source +- OpenAPI MCP From Remote Spec +- Hosted STDIO Input Shape + ## Remote MCP With No Auth Auth disabled means omit `auth_data`. From 9fe96605a13e423b2afac165ad545c979716a1c0 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Tue, 19 May 2026 14:21:52 -0700 Subject: [PATCH 5/5] Remove repo-local Codex hooks --- .codex/hooks.json | 25 ------------------------- .gitignore | 1 - 2 files changed, 26 deletions(-) delete mode 100644 .codex/hooks.json diff --git a/.codex/hooks.json b/.codex/hooks.json deleted file mode 100644 index 5cd1e72..0000000 --- a/.codex/hooks.json +++ /dev/null @@ -1,25 +0,0 @@ -{ - "SessionStart": [ - { - "command": ["bash", "./plugin-scripts/session-start.sh"], - "timeout": 30 - } - ], - "PreToolUse": [ - { - "match": { "tool": "shell" }, - "command": ["bash", "./plugin-scripts/block-delete-operations.sh"], - "timeout": 5 - }, - { - "match": { "tool": "shell" }, - "command": ["bash", "./hooks/auto-approve-tfy-api.sh"], - "timeout": 5 - }, - { - "match": { "tool": "shell" }, - "command": ["bash", "./plugin-scripts/pre-tool-secret-scan.sh"], - "timeout": 5 - } - ] -} diff --git a/.gitignore b/.gitignore index 6d2e2da..3152114 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ __pycache__/ .augment/ .claude/ .codex/ -!/.codex/hooks.json .codebuddy/ .commandcode/ .continue/