Hosted MCP

Connect to Flax's hosted HTTP MCP endpoint at POST /mcp, authenticated with OAuth

The hosted MCP endpoint lets remote and shared MCP clients connect to Flax over HTTP, without running a local binary. It exposes the same tool set as the local server. This page is for developers connecting a hosted MCP client.

#Endpoint

POST /mcp

Served from your Flax host, e.g. https://flax.example.com/mcp. It speaks the Model Context Protocol over Streamable HTTP.

Supported protocol revisions, newest first: 2025-06-18, 2025-03-26, 2024-11-05. The initialize handshake honours whichever of these your client asks for and answers with 2025-06-18 for anything else, so an unrecognised version degrades to a version Flax actually implements instead of being accepted blindly.

GET /mcp and DELETE /mcp return 405 Method Not Allowed by design, not as a gap. The Streamable HTTP transport only requires a GET SSE stream for server-initiated messages, and Flax's tool surface is pure request/response — no resources, prompts, sampling or server-initiated notifications — so there is no stream to open. Clients that probe GET first fall back to POST and work normally.

#Verify the endpoint

The reference client is the quickest check that a host is reachable, authenticated and serving tools:

npx @modelcontextprotocol/inspector --cli https://flax.example.com/mcp \
  --transport http --method tools/list \
  --header "Authorization: Bearer $FLAX_API_TOKEN"

That should print all tools from the tools reference. Swap --method tools/call --tool-name list_connections to exercise a real call end to end. Drop --cli for the interactive UI.

If you get 401, the response carries a WWW-Authenticate header naming the metadata document a client uses to discover OAuth:

WWW-Authenticate: Bearer resource_metadata="https://flax.example.com/.well-known/oauth-protected-resource"

That is the mechanism behind connecting with only a URL — see below.

#Authentication

The hosted endpoint is authenticated with OAuth. The client discovers Flax's authorization server, registers, and negotiates an interactive login and consent — see OAuth for MCP clients. The resulting access token is scoped (read/write) and every call is enforced against the user's team and row-level-security access.

Because Flax implements OAuth 2.1 with Dynamic Client Registration (RFC 7591) and PKCE, a client needs nothing but the URL: it reads the metadata above, registers itself, and opens a browser for login and consent. There is no client ID to provision and no token to paste.

Tip

Use hosted MCP when a client can't run a local process or when you want per-user, delegated access. For headless scripts on your own machine, the local stdio server with a static token is simpler.

#Connect a client

Point any Streamable-HTTP MCP client at https://your-flax-host/mcp.

Claude Code

claude mcp add --transport http flax https://flax.example.com/mcp

Clients configured by file (Claude Desktop, Cursor, VS Code, and others) take the same two facts — an HTTP transport and the URL:

{
  "mcpServers": {
    "flax": {
      "type": "http",
      "url": "https://flax.example.com/mcp"
    }
  }
}

Older clients that only speak stdio can bridge through the local server.

If a client offers no interactive login, authenticate with a service-account token instead of OAuth by sending Authorization: Bearer flax_pat_… (see Authentication). Tokens are scoped and RLS-enforced exactly like OAuth access tokens.

#Tools

The hosted endpoint offers the identical discover → validate → create tool set documented in the MCP tools reference.