[{"_1":2,"_170":-5,"_171":-5},"loaderData",{"_3":4,"_18":19,"_25":26,"_148":149},"root",{"_5":-5,"_6":-7,"_7":8,"_9":-7,"_10":11,"_12":-7,"_13":14,"_15":16,"_17":11},"currentUser","primaryEmail","siteVerification","6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI","toast","enableDev",false,"incidentStatus","theme","system","contrast","normal","dockerRebrandTour","routes/_layout",{"_20":-5,"_21":22,"_23":11,"_24":22},"username","isAskGordonEnabled",true,"showMinimalLanding","showHoneypotTrap","routes/_layout.r.$namespace.$reponame",{"_27":28,"_29":-5,"_30":11,"_31":11,"_32":33,"_34":35,"_36":-5,"_37":11,"_38":39,"_88":-5,"_89":90,"_135":-5,"_136":11,"_137":22,"_138":11,"_139":11,"_140":11,"_141":-5,"_142":11,"_143":-5,"_144":145,"_146":91,"_147":-7},"canonicalUrl","https://hub.docker.com/r/trackerforce/switcher-mcp-server/tags","mcpServer","canSeeDockerfile","canSeeAutobuilds","namespace","trackerforce","reponame","switcher-mcp-server","cloudBuildSource","isAutobuildsAvailable","repo",{"_40":41,"_42":43,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":55,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":74,"_79":11,"_80":81,"_85":33,"_86":87},"categories",[],"content_types",[44],"image","date_registered","2026-10-09T02:46:45.298233Z","description","","is_private","last_updated","2026-11-08T00:13:09.695884Z","last_modified","2026-11-09T00:04:58.948031Z","media_types",[56],"application/vnd.oci.image.index.v1+json","name","pull_count",781,"repository_type","star_count",0,"status",1,"status_description","active","source","collaborator_count","full_description","***\n\n

\nSwitcher MCP Server
\nMCP Server for Switcher API\n

\n\n***\n\n![Switcher API: Cloud-based Feature Flag API](https://raw.githubusercontent.com/switcherapi/switcherapi-assets/master/logo/switcherapi_mcp_server.png)\n\n# About\n\nSwitcher MCP Server exposes [Switcher API](https://github.com/switcherapi/switcher-api) feature\nflags to MCP-capable AI assistants (Claude Desktop, VS Code, GitHub Copilot CLI, etc.) as a set\nof MCP tools. It authenticates on behalf of a real Switcher API user/admin using an OAuth 2.1\nAuthorization Code + PKCE flow with Dynamic Client Registration, so no client secret is ever\nstored or shared.\n\nToggling feature flags will not be supported by this MCP Server for security and consistency reasons.\n\n# Quick Start\n\n### Requirements\n\n- Python 3.15+\n- [pipenv](https://pipenv.pypa.io/) for dependency management\n- A running [switcher-api](https://github.com/switcherapi/switcher-api) instance with OAuth enabled\n- A [switcher-management](https://github.com/switcherapi/switcher-management) instance for the\n browser-based consent screen (`/oauth/consent`)\n\n# Authentication\n\nHow authentication works depends on the transport.\n\n### Streamable HTTP transport\n\nThe MCP client (VS Code, Claude, etc.) performs the OAuth flow itself, **on the user's machine**,\nwhen it registers/connects to the MCP server.\n\n1. The client calls `/mcp` without a token and receives a `401` challenge whose\n `resource_metadata` points to the server's protected-resource metadata.\n2. The metadata advertises switcher-api as the authorization server. The client discovers its\n OAuth metadata and dynamically registers via `POST /oauth/register` (public, PKCE-only client).\n3. The client opens the consent page in the user's browser (switcher-management's `/oauth/consent`),\n which happens during MCP registration.\n4. The client exchanges the code for tokens via `POST /oauth/token` and sends the access token as a\n bearer token on every MCP request. The server forwards it to switcher-api, which validates it\n and its scopes.\n\nIf the token is rejected (e.g. consent revoked), tool calls fail with an error asking you to\nre-authorize the MCP client. Set `SWITCHER_MCP_PUBLIC_URL` when the server is reachable through a\ndifferent URL than `http://:`.\n\n### Stdio transport\n\nThe server is a local subprocess of the client, so it runs the authorization flow itself. When a\ntool call needs a Switcher API token and none is cached (or the cached one can't be refreshed), it\nruns the browser-based flow before retrying the call — the browser is **not** opened eagerly on\nserver startup. That flow:\n\n1. Discovers switcher-api's OAuth metadata from\n `GET {SWITCHER_API_URL}/.well-known/oauth-authorization-server`.\n2. Dynamically registers itself as an OAuth client via `POST /oauth/register` (no client secret\n — a public, PKCE-only client) and persists the issued `client_id` locally.\n3. Opens your default browser (the server runs on your machine) to\n switcher-management's consent screen so you can log in (if needed) and approve access.\n4. Receives the authorization code on a local loopback callback (`http://127.0.0.1:/callback`)\n and exchanges it for an access/refresh token pair via `POST /oauth/token`.\n\nIn stdio mode, credentials (client id, tokens, expiry) are cached at `~/.switcher-mcp/credentials.json`\n(file permissions restricted to the current user on POSIX systems) and refreshed automatically\nusing the rotating refresh token. If the refresh token itself expires, the next tool call will\nreopen the browser to re-authorize automatically; if you never complete the consent step, the\nauthorization attempt times out and the tool call fails with an error telling you to retry.\n\nYou can revoke access at any time from switcher-management's **Settings → Authorized Apps** page.\n\n# Running the Server\n\nConfigure the target switcher-api instance via the `SWITCHER_API_URL` environment variable or the\n`--api-url` CLI flag (defaults to `http://127.0.0.1:3000`).\n\n### Stdio Transport\n\nFor the default stdio transport:\n\n```bash\npipenv run python -m switcher_mcp_server.server --api-url https://switcherapi.com/api\n```\n\n### Streamable HTTP Transport (embedded uvicorn - single worker)\n\nFor a hosted/remote MCP server:\n\n```bash\npipenv run python -m switcher_mcp_server.server --transport streamable-http --host 0.0.0.0 --port 8000\n```\n\nThe server will be reachable at `http://:/mcp`.\n\n### Streamable HTTP Transport (external uvicorn - multiple workers)\n\nFor containerized/production deployments that need custom TLS certificates\nor multiple workers, run `switcher_mcp_server.asgi:create_app` with your own uvicorn process\ninstead (the `--factory` flag is required, since the app is built from a factory function):\n\n```bash\npipenv run uvicorn switcher_mcp_server.asgi:create_app \\\n --factory \\\n --host 0.0.0.0 \\\n --port 8443 \\\n --ssl-certfile=/etc/certs/ca.crt \\\n --ssl-keyfile=/etc/certs/ca.key \\\n --workers 4\n```\n\nIf the target switcher-api instance is also served under that certificate, set\n`SWITCHER_API_CERT_PATH` to the same cert file so outbound requests verify against it instead of\nthe default CA bundle:\n\n```bash\nexport SWITCHER_API_CERT_PATH=/etc/certs/ca.crt\n```\n\n## Configuration\n\n| Variable | CLI flag | Default | Description |\n|----------------------------|---------------------|--------------------------------|------------------------------------------------|\n| `SWITCHER_API_URL` | `--api-url` | `http://127.0.0.1:3000` | Base URL of the target switcher-api instance |\n| `SWITCHER_API_INTERNAL_URL`| `--api-internal-url`| unset (uses `SWITCHER_API_URL`)| Internal switcher-api URL used only for server-side tool requests |\n| `SWITCHER_API_CERT_PATH` | — | unset | Path to the TLS certificate for Switcher API |\n| `SWITCHER_MCP_TRANSPORT` | `--transport` | `stdio` | `stdio` or `streamable-http` |\n| `SWITCHER_MCP_HOST` | `--host` | `0.0.0.0` | Bind host for the streamable HTTP transport |\n| `SWITCHER_MCP_PORT` | `--port` | `8000` | Bind port for the streamable HTTP transport |\n| `SWITCHER_MCP_PUBLIC_URL` | `--public-url` | `http://:` | Externally reachable MCP URL used as the OAuth resource identifier (streamable HTTP only) |\n| `SWITCHER_MCP_CREDENTIALS_PATH` | — | `~/.switcher-mcp/credentials.json` | Override the persisted OAuth credentials cache location |\n\nCLI flags take precedence over environment variables.\n\n### Internal API URL (hosted deployments)\n\n`SWITCHER_API_URL` is the **public** URL: it is used for OAuth issuer discovery, authorization,\ntoken and refresh requests. Optionally, `SWITCHER_API_INTERNAL_URL` points MCP server-to-API tool\nrequests at an internal endpoint (e.g. a Kubernetes service), bypassing the public ingress. The\ninternal URL is never advertised to OAuth clients. When unset, tool requests use `SWITCHER_API_URL`.\n\n```yaml\nenv:\n - name: SWITCHER_API_URL\n value: https://switcherapi.com/api\n - name: SWITCHER_API_INTERNAL_URL\n value: http://switcher-api.switcherapi.svc.cluster.local:3000\n```\n\n## MCP Client Configuration\n\nExample stdio configuration for an MCP client (e.g. Claude Desktop, VS Code):\n\n```json\n{\n \"mcpServers\": {\n \"switcher\": {\n \"command\": \"pipenv\",\n \"args\": [\"run\", \"python\", \"-m\", \"switcher_mcp_server.server\"],\n \"cwd\": \"/path/to/switcher-mcp-server\",\n \"env\": {\n \"SWITCHER_API_URL\": \"https://switcherapi.com/api\"\n }\n }\n }\n}\n```\n\n# Available Tools\n\n| Tool | Description |\n|---------------------|------------------------------------------------------------------------------|\n| `list_domains` | List the domains the authenticated user owns and/or collaborates on. |\n| `list_environments` | List environment names for a given domain id. |\n| `get_feature_flag` | Get a feature flag's settings by key, domain name, and optional environment. |\n\n# Available Prompts\n\nPrompts are user-selectable, guided templates (e.g. shown as `/switcher_domains` in MCP clients)\nthat drive one of the tools above and ask the model to summarize or analyze its result. All\nprompts are prefixed with `switcher_` for easy discovery.\n\n| Prompt | Drives | Description |\n|--------------------------|----------------------|---------------------------------------------------------------------|\n| `switcher_domains` | `list_domains` | Discover and summarize the Switcher domains accessible to the authenticated user. |\n| `switcher_environments` | `list_environments` | List a Switcher domain's environments. |\n| `switcher_get_feature` | `get_feature_flag` | Fetch a Switcher feature flag's settings. |\n\n# Development\n\n## Quality Gate\n\n```bash\nmake install # pipenv install --dev\nmake lint # pylint switcher_mcp_server\nmake test # pytest with coverage (coverage.xml)\nmake cover # generate an HTML coverage report (htmlcov/)\nmake e2e-tools # manual, configurable e2e tool validation (see scripts/e2e/README.md)\nmake e2e-prompts # manual, configurable e2e prompt validation (see scripts/e2e/README.md)\n```\n\nBoth `pylint` and `pytest` must pass before merging changes. Tests use `pytest-httpx` to mock all\noutbound HTTP calls to switcher-api — no live server is required to run the test suite.\n\n## Contributing\n\nRead our [Contributing](https://github.com/switcherapi/switcher-mcp-server/blob/master/CONTRIBUTING.md)\nguide to learn about our development process, and how to propose enhancements and improvements.\n\n# AI Disclaimer\n\nThis project was designed and implemented with AI-assisted tools. We have thoroughly reviewed and tested all AI-generated contributions to ensure they meet our quality standards and align with our project's goals. We are committed to transparency about our use of AI and will continue to disclose any significant AI contributions in the future.\n\nExternal contributions from the community are **equally valued and will be reviewed with the same standards, regardless of whether they were assisted by AI or not**. We encourage all contributors to disclose their use of AI tools in their contributions to maintain transparency and foster trust within our community.","has_starred","hub_user","immutable_tags_settings",{"_75":11,"_76":77},"enabled","rules",[78],".*","is_automated","permissions",{"_82":22,"_83":11,"_84":11},"read","write","admin","user","storage_size",1395659402,"orgData","recentTags",[91],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_101":102,"_50":124,"_125":94,"_126":33,"_127":56,"_57":128,"_129":130,"_131":109,"_132":124,"_133":66,"_134":22},"content_type","creator",13989068,"digest","sha256:912e06506c8ea8ed433c9bfa81a84495ea150bccce31251c7d18dc59c0b13817","full_size",78075050,"id",1341743374,"images",[103,118],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},"architecture","amd64","sha256:f9377f500975030c42723c4acf21967e577d71032e0bdcf692f3567ac4eeb9b4","features","last_pulled","2026-11-11T00:45:48.076977641Z","last_pushed","2026-11-08T00:13:07.079882983Z","os","linux","os_features","os_version","size","variant",{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},"arm64","sha256:94a5ca2034f3ff91d64a8021b1caf95c7fec69acd0053ceff332c77da1faa9ef","2026-11-10T03:56:12.48104913Z","2026-11-08T00:13:07.594084612Z",77672070,"2026-11-08T00:13:09.201542Z","last_updater","last_updater_username","media_type","latest","repository",32807325,"tag_last_pulled","tag_last_pushed","tag_status","v2","sbxKitMetadata","isPotentialSpam","isHubSbxKitsEnabled","showSbxRunInCloud","showSbxAgenticPlatformBadge","showSbxLogoOverride","sbxTrademarkText","displaySecurityMetadata","tagAttestations","tagsHaveAttestations",[],"selectedTag","attestationsUrl","routes/_layout.r.$namespace.$reponame.tags",{"_38":150,"_157":158,"_144":168,"_169":11},{"_40":151,"_42":152,"_45":46,"_47":48,"_49":11,"_50":51,"_52":53,"_54":153,"_57":35,"_32":33,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":-5,"_68":62,"_69":70,"_71":11,"_72":33,"_73":154,"_79":11,"_80":156,"_85":33,"_86":87},[],[44],[56],{"_75":11,"_76":155},[78],{"_82":22,"_83":11,"_84":11},"tags",{"_159":64,"_160":-5,"_161":-5,"_162":163},"count","next","previous","results",[164],{"_92":44,"_93":94,"_95":96,"_97":98,"_99":100,"_101":165,"_50":124,"_125":94,"_126":33,"_127":56,"_57":128,"_129":130,"_131":109,"_132":124,"_133":66,"_134":22},[166,167],{"_104":105,"_95":106,"_107":48,"_108":109,"_110":111,"_112":113,"_114":48,"_115":-5,"_116":98,"_63":66,"_117":-5},{"_104":119,"_95":120,"_107":48,"_108":121,"_110":122,"_112":113,"_114":48,"_115":-5,"_116":123,"_63":66,"_117":-5},[],"canDeleteTags","actionData","errors"]

Digest	OS/ARCH	Compressed size
f9377f500975	linux/amd64	74.46 MB
94a5ca2034f3	linux/arm64	74.07 MB

trackerforce/switcher-mcp-server

Tags for trackerforce/switcher-mcp-server