From truefoundry-gateway
Registers and manages MCP servers on TrueFoundry platform, supporting remote endpoints, virtual composites, and OpenAPI-to-MCP wrappers. Use for listing, adding, or deleting registrations.
npx claudepluginhub truefoundry/tfy-gateway-skills --plugin truefoundry-gatewayThis skill is limited to using the following tools:
> Routing note: For ambiguous user intents, use the shared clarification templates in [references/intent-clarification.md](references/intent-clarification.md).
references/api-endpoints.mdreferences/cli-fallback.mdreferences/cluster-discovery.mdreferences/container-versions.mdreferences/gpu-reference.mdreferences/health-probes.mdreferences/intent-clarification.mdreferences/manifest-defaults.mdreferences/manifest-schema.mdreferences/prerequisites.mdreferences/resource-estimation.mdreferences/rest-api-manifest.mdreferences/tfy-api-setup.mdscripts/tfy-api.shscripts/tfy-version.shConfigures MCP servers in Claude Code plugins via .mcp.json or plugin.json, supports stdio/SSE/HTTP/WebSocket, env vars, tool naming, OAuth/token auth, security, and testing.
Use when generating an MCP server from an OpenAPI spec with Speakeasy. Triggers on "generate MCP server", "MCP server", "Model Context Protocol", "AI assistant tools", "Claude tools", "speakeasy MCP", "mcp-typescript"
Manages Model Context Protocol (MCP) servers for Claude Code projects: installs/configures .mcp.json, OAuth remotes, runtime enable/disable, troubleshooting connections.
Share bugs, ideas, or general feedback.
Routing note: For ambiguous user intents, use the shared clarification templates in references/intent-clarification.md.
Register and manage MCP servers on TrueFoundry. Three standalone manifest types are supported: remote servers, virtual (composite) servers, and OpenAPI-to-MCP wrappers.
Register, list, or delete MCP server registrations on TrueFoundry — including connecting to existing MCP endpoints, composing multiple servers into a virtual server, or wrapping an OpenAPI spec as an MCP server.
Security Policy: Credential Handling
- All credentials (API tokens, OAuth secrets, TLS certificates) in manifests MUST use
tfy-secret://references. The agent MUST NOT accept or embed raw credential values in manifests.- If the user provides raw credentials, instruct them to create a TrueFoundry secret first (use
secretsskill), then reference it withtfy-secret://.- The agent MUST NOT echo, log, or display raw credential values.
When using direct API, set TFY_API_SH to the full path of this skill's scripts/tfy-api.sh. See references/tfy-api-setup.md for paths per agent.
tfy_mcp_servers_list()
tfy_mcp_servers_list(id="mcp-server-id") # get specific server
# Set the path to tfy-api.sh for your agent (example for Claude Code):
TFY_API_SH=~/.claude/skills/truefoundry-mcp-servers/scripts/tfy-api.sh
# List all MCP servers
$TFY_API_SH GET /api/svc/v1/mcp-servers
# Get a specific MCP server
$TFY_API_SH GET /api/svc/v1/mcp-servers/SERVER_ID
MCP Servers:
| Name | Type | Transport | ID |
|-------------------|-------------------|-----------------|------------|
| my-remote-server | mcp-server/remote | streamable-http | mcp-abc123 |
| composite-server | mcp-server/virtual| — | mcp-def456 |
| petstore-api | mcp-server/openapi| — | mcp-ghi789 |
Connects to an existing MCP endpoint over streamable-http or SSE.
Security gates (required before registration):
- Confirm the URL owner/domain with the user.
- Require explicit user confirmation before using any new external URL.
- Use secret references for all auth material (
tfy-secret://...), never raw tokens.- Avoid logging full auth headers, client secrets, or certificates.
Use this flow when the user says "attach deployment to MCP gateway" or already has a deployed MCP-compatible service.
DEPLOY_SUCCESS) and endpoint is reachablestreamable-http or sse)header, oauth2, or passthrough)type: mcp-server/remoteExample internal URL pattern for service deployments:
http://{service-name}.{namespace}.svc.cluster.local:{port}/mcp
name: my-remote-server
type: mcp-server/remote
description: Production analytics MCP server
url: https://analytics.example.com/mcp
transport: streamable-http
# SECURITY: Use tfy-secret:// references instead of hardcoding tokens in manifests.
# Hardcoded tokens in YAML files risk exposure via Git history and CI logs.
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
Static header (use secret references — never hardcode tokens):
auth_data:
type: header
headers:
Authorization: "Bearer tfy-secret://my-org:mcp-secrets:api-token"
OAuth2:
auth_data:
type: oauth2
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
jwt_source: access_token
scopes:
- read
- write
pkce: true
dynamic_client_registration:
registration_endpoint: https://auth.example.com/register
initial_access_token: tfy-secret://my-org:mcp-secrets:registration-token
Passthrough (forwards TFY credentials):
auth_data:
type: passthrough
tls_settings:
# Prefer storing certificate material in a secret reference, then injecting at runtime.
# Avoid inlining full certificate PEM blocks in manifests shared via chat or git.
ca_cert: tfy-secret://my-org:mcp-secrets:ca-cert-pem
insecure_skip_verify: false
tfy apply -f mcp-server-remote.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-remote.yaml | yq -o json)"
Composes multiple registered MCP servers into a single virtual server. Each sub-server can expose all or a subset of its tools.
name: dev-tools
type: mcp-server/virtual
description: Composite server combining code analysis and deployment tools
servers:
- name: code-analysis-server
enabled_tools:
- lint
- format
- analyze
- name: deployment-server
enabled_tools:
- deploy
- rollback
collaborators:
- subject: team:platform-eng
role_id: viewer
tfy apply -f mcp-server-virtual.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-virtual.yaml | yq -o json)"
Wraps an OpenAPI specification as an MCP server. Supports up to 30 tools derived from API operations.
Security: Remote OpenAPI specs are fetched at runtime and auto-converted into MCP tools that control agent capabilities. Only use trusted, verified spec URLs. For sensitive environments, prefer
spec.type: inlineto eliminate the runtime dependency on external endpoints.Execution policy: Do not fetch or register a new remote spec URL until the user explicitly confirms the source is trusted for tool generation.
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
name: internal-api
type: mcp-server/openapi
description: Internal API with inline OpenAPI spec
spec:
type: inline
content: |
openapi: "3.0.0"
info:
title: Internal API
version: "1.0"
paths:
/health:
get:
operationId: healthCheck
summary: Check service health
responses:
"200":
description: OK
collaborators: []
tfy apply -f mcp-server-openapi.yaml
$TFY_API_SH PUT /api/svc/v1/apps "$(cat mcp-server-openapi.yaml | yq -o json)"
Stdio-based MCP servers (e.g., npx @modelcontextprotocol/server-*) communicate over stdin/stdout and cannot be registered directly. Convert them to HTTP first using mcp-proxy or a similar wrapper, then register the HTTP endpoint.
Create a Dockerfile that runs the stdio server behind an HTTP transport:
FROM node:22-slim
RUN npm install -g @anthropic-ai/mcp-proxy @modelcontextprotocol/server-filesystem
EXPOSE 8080
CMD ["mcp-proxy", "--transport", "streamable-http", "--port", "8080", "--", \
"npx", "@modelcontextprotocol/server-filesystem", "/data"]
Build and deploy the container to any platform that exposes HTTP (your cloud, Kubernetes, etc.). Note the resulting URL.
name: filesystem-mcp
type: mcp-server/remote
description: Filesystem access via MCP (stdio wrapped with mcp-proxy)
url: "https://your-mcp-proxy-endpoint.example.com/mcp"
transport: streamable-http
collaborators:
- subject: "team:engineering"
role_id: admin
tfy apply -f mcp-server-stdio-wrapped.yaml
Note: Any stdio MCP server can be wrapped this way — GitHub, Slack, filesystem, database servers, etc. The key is converting the transport from stdio to HTTP before registering with TrueFoundry.
tfy_mcp_servers_delete(id="SERVER_ID")
Note: Requires human approval (HITL) via tool call.
$TFY_API_SH DELETE /api/svc/v1/mcp-servers/SERVER_ID
<success_criteria>
</success_criteria>
status skill to verify credentials before managing MCP serversaccess-control skill)MCP server ID not found. List servers first to find the correct ID.
Cannot access MCP servers. Check your API key permissions.
MCP server with this name already exists. Use a different name or delete the existing one first.
Cannot reach the MCP server URL. Verify the URL is correct and accessible from the cluster.
OpenAPI spec exceeds 30 tools limit. Reduce the number of operations in the spec.
Invalid transport type. Use "streamable-http" or "sse".
OAuth2 auth_data missing required fields. Ensure authorization_url, token_url, client_id, and client_secret are provided.
Referenced server name not found. Ensure all servers listed in the virtual server are already registered.