> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/api-reference/mcp.md). # MCP The sfp server exposes its API to AI agents over MCP (Model Context Protocol). A connected agent can read projects, builds, releases, release candidates, validations, reviews, work items, environments, orgs, and pools from your instance, and check out pool environments — as you, with your permissions. ## Endpoint Your MCP endpoint is your sfp instance URL with `/sfp/api/mcp` appended: ``` https://.flxbl.io/sfp/api/mcp ``` | Property | Value | | --------- | ------------------------------------------------------- | | Transport | Streamable HTTP | | Protocol | MCP 2025-06-18 | | Auth | OAuth 2.1 (interactive) or application token (headless) | ## Authentication Connections use **OAuth 2.1** by default: add the endpoint with no credentials. The server answers the first unauthenticated request with a challenge that names its authorization server; your client opens a browser sign-in — the same identity provider you sign in to the product with — and you approve the connection once. From then on every tool call runs with your user's role, and environment checkouts are attributed to your email. For headless use — CI, scripted clients — pass an **application token** as a bearer header instead. Token calls authenticate with the application role and are not tied to a person. Create a token: ```bash sfp server auth login sfp server application-token create --name "mcp-ci" --expires-in 90 ``` {% hint style="warning" %} The token is displayed once at creation. Store it in a secret manager. {% endhint %} ## Setup ### Claude Code ```bash claude mcp add --transport http sfp https://.flxbl.io/sfp/api/mcp ``` Inside a Claude Code session, run `/mcp` and select **sfp** to authenticate. The browser opens your server's sign-in; `claude mcp list` shows **✔ Connected** once the flow completes (until then it reads **! Needs authentication**). For a headless setup, pass an application token as a header instead of authenticating: ```bash claude mcp add --transport http sfp https://.flxbl.io/sfp/api/mcp \ --header "Authorization: Bearer YOUR_APP_TOKEN" ``` ### Codex ```bash codex mcp add sfp --url https://.flxbl.io/sfp/api/mcp codex mcp login sfp ``` `codex mcp login` runs the OAuth flow in the browser. The equivalent entry in `~/.codex/config.toml`: ```toml [mcp_servers.sfp] url = "https://.flxbl.io/sfp/api/mcp" ``` For a headless setup, keep an application token in an environment variable and reference it: ```toml [mcp_servers.sfp] url = "https://.flxbl.io/sfp/api/mcp" bearer_token_env_var = "SFP_APP_TOKEN" ``` `codex mcp list` shows each server's connection and authentication status. ### Claude Desktop and claude.ai Go to **Settings > Connectors > Add custom connector**, name it `sfp`, and enter the endpoint URL. The first use triggers the browser sign-in. ### Other clients Any client that supports the streamable HTTP transport connects with the same URL. The generic configuration: ```json { "mcpServers": { "sfp": { "type": "http", "url": "https://.flxbl.io/sfp/api/mcp" } } } ``` For Cursor this goes in `.cursor/mcp.json`, for GitHub Copilot in `.vscode/mcp.json`. Clients without an OAuth flow can pass an application token instead: ```json { "mcpServers": { "sfp": { "type": "http", "url": "https://.flxbl.io/sfp/api/mcp", "headers": { "Authorization": "Bearer YOUR_APP_TOKEN" } } } } ``` ### Verify Ask the agent: *"List the available pools."* If it returns pool data, you are connected. ## Identity and write actions Most tools are read-only. The write actions — `fetch_pool_env`, `extend_pool_env`, `release_pool_env` on the `pools` tool — change state in your instance, and who the caller is decides how they run: * A **signed-in user** (OAuth) acts as themselves. A pool checkout is assigned to the caller's email, and a user can fetch, extend, release, or list environments only for their own account. * An **application token** may act for any server member — it is meant for automation that operates on behalf of others. ## Available tools | Tool | Actions | Reads | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | `projects` | `list_projects`, `get_project` | sfp project configuration and repository metadata | | `builds` | `get_build_status` | Build status for repositories and domains | | `releases` | `get_releases`, `get_release_change_summary` | Deployed and pending releases across release environments | | `release_candidates` | `list_release_candidates` | Release candidate records and deployment readiness | | `validations` | `list_validation_results`, `get_pr_validation`, `list_validation_statuses`, `list_analysis_results`, `get_pr_analysis` | PR validation results (deployment + tests) and PR analysis results (linters, compliance) | | `reviews` | `get_review_status` | Pull request review status, checks, and review environment details | | `work_items` | `get_work_item`, `list_work_items` | Work items from configured Jira, Azure DevOps, or GitHub providers | | `environments` | `list_environments` | Registered environments and environment groups | | `orgs` | `list_orgs_meta` | Org metadata from registered and pool-backed orgs | | `pools` | `list_pools`, `get_pool_status`, `list_pool_envs`, `list_pool_assignments`, `fetch_pool_env`, `extend_pool_env`, `release_pool_env` | Pool configurations and availability; the last three actions check out, extend, and release environments | | `insights` | `get_performance_dashboard` | CI/CD performance metrics for a repository | | `review_envs` | `list_review_envs` | Review environment assignments for PRs, issues, and users | Each action's input schema is served by the instance itself: ```bash curl -s -H "Authorization: Bearer YOUR_TOKEN" \ https://.flxbl.io/sfp/api/mcp/tools ``` ## Troubleshooting An unauthenticated request returns `401` with a `WWW-Authenticate` challenge pointing at the resource metadata — this is what OAuth clients consume to discover the authorization server: ```bash curl -si https://.flxbl.io/sfp/api/mcp | grep -i www-authenticate curl -s https://.flxbl.io/.well-known/oauth-protected-resource/sfp/api/mcp ``` [MCP Inspector](https://github.com/modelcontextprotocol/inspector) tests the endpoint interactively — complete the OAuth flow in the opened browser, or enter an application token in the **Bearer Token** field: ```bash npx @modelcontextprotocol/inspector \ --transport streamable-http \ --url https://.flxbl.io/sfp/api/mcp ``` | Error | Cause | Fix | | -------------------------------- | -------------------------------------- | -------------------------------------------------------------------- | | `401 Unauthorized` | Missing or expired credentials | Re-authenticate from the client, or create a new application token | | `Not Acceptable` | Missing Accept header | Include `Accept: application/json, text/event-stream` | | Write action refused | User caller acting for another account | Pool write actions run against the signed-in user's own account only | | `isError: true` in tool response | Tool-level error (e.g. pool not found) | Read the message; `list_pools` discovers valid pools | ## Related * [Review Environments](/flxbl/sfp/environment-management/overview.md) * [Pools](/flxbl/sfp/environment-management/pools.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.flxbl.io/flxbl/sfp/api-reference/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.