Connect Claude

Every Flux API exposes a built-in MCP server at /{api_prefix}/_mcp. Point Claude — or any Model Context Protocol client — at that URL and the model gains five read tools: resource discovery, schema introspection, get record, list records, and search — plus two opt-in write tools when the key grants them. No SDK wrapper. No glue layer.

This guide walks through verifying the endpoint with curl, then connecting it to Claude Code (or any other MCP-aware client) as a runtime tool source.

Prerequisites

Before you start:

1. A Flux API with at least one connected collection. See Expose Content via Flux API.
2. Your environment key (e.g., 7c9h4pwu) and API prefix (e.g., blog) — both visible in the Flux API page of the dashboard.
3. A Flux API key if the API has is_auth_required: true — used as a public_key/secret_key pair, or as a bearer token for hosted connectors. See Manage Roles and API Keys. Public APIs work without keys.
4. An MCP-aware client. This guide uses Claude Code, but any client that supports the MCP Streamable HTTP transport works the same way.

What you get

Connecting Claude to your Flux API via MCP gives the model a tool catalog scoped to the connected collections of the chosen prefix. Five read tools are always present:

Two write tools — create_record and update_record — appear additionally when the key's role grants create/update on the API. Writes publish immediately and only land in collections whose connection explicitly allows them, so an agent can read the whole knowledge base but write only into, say, its memory collection.

All tools respect the same permissions as the REST surface — is_auth_required, allowed_methods per collection (get_one / get_many / create / update), and the API key's role. If a collection is connected with only get_many, the agent gets query_records and search_records but not get_record.

Step 1 – Verify the endpoint

Before wiring it into a client, confirm the MCP endpoint is reachable and responsive. Two raw curl calls — initialize, then tools/list.

# Replace with your env_key and api_prefix.
URL=https://7c9h4pwu.fxns.io/blog/_mcp

# 1. Initialize a session. Grab the Mcp-Session-Id from the response headers.
SID=$(curl -sS -i -X POST $URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id" {gsub(/\r/,"",$2); print $2}')

# 2. List the available tools.
curl -sS -X POST $URL \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

You should see a JSON-RPC response listing five read tools (discover_resources, describe_resource, get_record, query_records, search_records) with their input schemas — plus create_record and update_record if your key's role grants writes.

Step 2 – Wire it into Claude Code

Claude Code (the CLI agent) accepts HTTP-based MCP servers directly. Register the Flux API as an MCP server with:

claude mcp add --transport http foxnose-blog https://7c9h4pwu.fxns.io/blog/_mcp \
  --header "Authorization: Simple $FOXNOSE_PUBLIC_KEY:$FOXNOSE_PRIVATE_KEY"

Drop the --header flag if the API is public.

In a Claude Code session, the tools then appear under the foxnose-blog prefix:

foxnose-blog__discover_resources
foxnose-blog__describe_resource
foxnose-blog__get_record
foxnose-blog__query_records
foxnose-blog__search_records

You can confirm the server is connected with:

claude mcp list

Step 3 – Other MCP-aware clients

Any client that implements MCP Streamable HTTP 2025-03-26 works the same way. The common config shape is:

{
  "mcpServers": {
    "foxnose-blog": {
      "type": "http",
      "url": "https://7c9h4pwu.fxns.io/blog/_mcp",
      "headers": {
        "Authorization": "Simple ${FOXNOSE_PUBLIC_KEY}:${FOXNOSE_PRIVATE_KEY}"
      }
    }
  }
}

Drop the headers block for public APIs. The exact file location and key names depend on the client — consult its docs. Clients that only speak stdio MCP (no HTTP transport) need a bridge such as mcp-proxy in between.

Step 4 – Hosted connectors (Claude API)

The configuration above assumes you can write the Authorization header. A hosted connector cannot: it takes a token value and sends it as Authorization: Bearer <token>, with no way to choose the scheme. The Claude API's MCP connector works this way, through mcp_servers[].authorization_token.

For those, issue a Bearer token on the Flux key you want the connector to act as:

curl -X POST https://api.foxnose.net/v1/7c9h4pwu/permissions/flux-api/api-keys/dw2qC5qRwxuZ/bearer-token/ \
  -H "Authorization: Bearer $MANAGEMENT_ACCESS_TOKEN"

The response contains bearer_token — an fxk_... value shown once. Pass it as the connector's token:

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    { "role": "user", "content": "Save a note in my memory collection, then read it back." }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "url": "https://7c9h4pwu.fxns.io/blog/_mcp",
      "name": "foxnose-blog",
      "authorization_token": "fxk_A7fQ2mXe..."
    }
  ]
}

To cut the connector off, re-issue the token — the previous one stops working while everything using the key's public/private pair carries on. Do not confuse the two Bearer credentials in the snippets above: the curl uses your Management API JWT, the connector uses the fxk_ token.

Hiding the agent surface for a specific API

By default, every Flux API has mcp_enabled: true and router_introspection_enabled: true — agent-facing endpoints are reachable. If you have an API prefix that should serve REST traffic but stay invisible to agents (legacy clients, partner-only feeds, etc.), flip the per-API toggle through the Management API:

curl -X PATCH https://api.foxnose.net/v1/7c9h4pwu/api/dw2qC5qRwxuZ/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiI..." \
  -H "Content-Type: application/json" \
  -d '{"mcp_enabled": false, "router_introspection_enabled": false}'

The REST endpoints (/{collection}, /{collection}/_search, /{collection}/{key}) continue to work. Only /{api_prefix}/_mcp and /{api_prefix}/_router start returning 404.

See Flux APIs Management → Flux API Object for the field definitions.

How it differs from a custom MCP server

Most MCP integrations require writing a server: define tools, wire each to a backend call, handle auth, ship a binary, keep the schema in sync. FoxNose flips that:

• Built-in, not bolted on. The MCP server is part of every Flux API — there is no separate process to deploy or operate.
• Schema-driven tool inputs. describe_resource returns the live JSON Schema of any connected collection, so agents can reason about field types and searchable fields without hardcoded knowledge.
• Same permissions, same data. No second access-control surface to maintain. If a collection is read-only for a key via REST, it is read-only for that key via MCP — and writes require an explicit opt-in on both the key's role and the collection connection.
• Per-API isolation. Each prefix gets its own catalog. A blog prefix only exposes blog content; a legal-kb prefix only exposes legal content. Use this to scope agents tightly.

What's next?

Explore the protocol details. The full MCP server reference covers session lifecycle, JSON-RPC error codes, rate limits, and the tool result envelope.

Discover routes at runtime. If you're building a custom agent rather than using an MCP client, the router introspection endpoint gives you a flat list of every REST route under a prefix.

Know what it costs. Each tools/call your agent makes counts as one retrieval against your plan; the handshake calls (initialize, tools/list, ping) are free.