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-only tools: schema discovery, list, get one, search, and vector search. 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:

A Flux API with at least one connected folder. See Expose Content via Flux API.
Your environment key (e.g., 7c9h4pwu) and API prefix (e.g., blog) — both visible in the Flux API page of the dashboard.
A Flux API key pair (access_key + secret_key) if the API has is_auth_required: true. See Manage Roles and API Keys. Public APIs work without keys.
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 fixed read-only tool catalog, scoped to the connected folders of the chosen prefix:

Tool	Backed by	What it returns
`discover`	Folder list	Names, aliases, and descriptions of every folder reachable through this API prefix
`get_schema`	`/{folder}/_schema`	JSON Schema, searchable fields, and locale metadata for a folder
`get_one`	`GET /{folder}/{key}`	A single resource by key
`list`	`GET /{folder}`	Paginated list of resources
`search`	`POST /{folder}/_search`	Full-text, semantic, hybrid, or filtered search

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

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 tools (discover, get_schema, get_one, list, search) with their input schemas.

For the Authorization: Secure signature format, see Flux API Authentication. Anonymous traffic is allowed on public APIs (is_auth_required: false).

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: Secure $FOXNOSE_ACCESS_KEY:$FOXNOSE_SIGNATURE"

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

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

foxnose-blog__discover
foxnose-blog__get_schema
foxnose-blog__list
foxnose-blog__get_one
foxnose-blog__search

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": {
      "transport": "http",
      "url": "https://7c9h4pwu.fxns.io/blog/_mcp",
      "headers": {
        "Authorization": "Secure ${FOXNOSE_ACCESS_KEY}:${FOXNOSE_SIGNATURE}"
      }
    }
  }
}

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.

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 (/{folder}, /{folder}/_search, /{folder}/{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. get_schema returns the live JSON Schema of any connected folder, 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 folder is read-only via REST, it is read-only via MCP.
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.

MCP Server Reference

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.

Router Introspection