Agent-Native Flux APIs

Every Flux API you create on FoxNose is agent-native by default. The same URL prefix that serves your REST endpoints also exposes a Model Context Protocol server, a route catalog, and per-folder JSON Schema — discoverable at runtime, gated by the same permissions, scoped to the connected folders. No SDK to install. No glue layer to write. No second tool surface to maintain.

This page explains what "agent-native" means in practice, how the three introspection endpoints fit together, when to use MCP vs. a hand-written integration, and how to control which APIs are visible to agents.

What "agent-native" means here

Most platforms that integrate with AI agents take one of two paths:

1. SDK-based. You install a client library, instantiate a class, write retriever or tool wrappers around the SDK's methods, and ship them to your agent framework. Every new tool or schema change means another code update on the consumer side.
2. Custom MCP server. You build a small MCP server in front of an existing API. You define the tools, wire each to an HTTP call, handle auth, ship a binary, and keep the schema in sync as the upstream API evolves.

FoxNose collapses both into the Flux API itself. Every prefix already has:

https://{environment_key}.fxns.io/{api_prefix}/_mcp        # MCP server (Streamable HTTP)
https://{environment_key}.fxns.io/{api_prefix}/_router     # Flat route catalog
https://{environment_key}.fxns.io/{api_prefix}/{folder}/_schema   # JSON Schema per folder

…sitting next to the data routes (/{folder}, /{folder}/{key}, /{folder}/_search). Nothing to deploy, nothing to keep in sync — the introspection endpoints read the same configuration the REST endpoints already use.

The three introspection endpoints

The three are designed to compose: an agent can call /_router to discover what routes exist, /{folder}/_schema to learn what each one expects, and /_mcp to invoke them with proper input validation — or short-circuit the whole thing by using the MCP server, which already wraps all of the above into tools.

What makes this agent-native, not just MCP-enabled

Plenty of platforms now bolt MCP onto an existing API surface. The differences worth knowing about — what makes FoxNose specifically built for agents rather than retrofitted for them:

• Hybrid search arrives as one tool. The search tool wraps FoxNose's hybrid retrieval — vector similarity, full-text matching, and structured filters in a single call. The agent gets state-of-the-art retrieval without you choosing modes or writing fan-out logic between separate search backends. A typical hand-rolled tool surface would expose three or four narrower search tools and let the model pick poorly between them; here, one tool does the right thing.
• Constant tool count, regardless of content size. The five tools (discover, get_schema, get_one, list, search) work across every connected folder via a folder_path argument. Adding a tenth folder, or a hundredth, doesn't grow the catalog or confuse the model — it expands what the existing tools can reach. Hand-rolled MCP servers tend to inflate one-tool-per-resource and overflow the model's tool budget.
• Schema-driven tool inputs, no drift. The get_schema tool returns the live JSON Schema of any folder — including which fields are searchable, which are vectorized, and which locales are configured. The agent can validate its tool calls against the current schema before issuing them. Hand-written MCP servers maintain a separate copy of the schema in the tool definitions and drift the moment the upstream schema changes.
• Localization-aware. Every folder's schema exposes its configured locales. An agent that talks to a multilingual knowledge base can ask get_schema once, then call search/get_one with the right locale argument — no separate "EN tool" and "FR tool". This is unusual; most agent tool surfaces treat localization as the application's problem.
• Versioning-aware. FoxNose supports schema versioning. You can pin an agent to a specific version of the schema, migrate the underlying schema, and only roll the agent forward when its prompt and reasoning are ready for the new shape. No more "schema change broke production agents at 3am" surprises.
• One source of truth for permissions. The agent inherits exactly the access rights of its Flux API key. There is no separate "allowed tools" list to keep in sync, no second role system, no chance an agent sees something the equivalent REST request would be denied (see below).

These six properties are what we mean by "agent-native": the system is designed so that adding agents doesn't add a parallel stack to maintain.

Same auth, same permissions

There is no second access-control surface for agents. The introspection endpoints inherit the existing Flux API model:

• is_auth_required on the API row controls whether a Flux API key is required for any traffic — including /_mcp, /_router, and /_schema. Public APIs accept anonymous traffic everywhere; private APIs require the Authorization: Secure <access_key>:<signature> header everywhere.
• allowed_methods on the per-folder connection (get_one, get_many) controls which MCP tools the agent gets per folder. A folder connected with only get_many exposes list and search but not get_one — same as the REST surface.
• Flux API key roles apply the same way. A read-only key on a private API works for all five MCP tools; a key without read on a specific folder can't see that folder via MCP either.

If a folder is read-only via REST, it is read-only via MCP. If a folder is invisible to a given key via REST, it is invisible via MCP. The model is the same model — that's the whole point.

Governing agent visibility per API

Not every knowledge surface should be discoverable by autonomous agents. Some content has legal or contractual constraints on automated access. Some prefixes are partner-only and shouldn't appear in any agent's tool catalog. Some you want to roll out to agents on staging first and only enable on production after validation. The Flux API gives you two governance toggles per prefix, set independently:

• mcp_enabled (default true) — when false, /{api_prefix}/_mcp returns 404. The MCP tool surface for this prefix is invisible to all clients.
• router_introspection_enabled (default true) — when false, /{api_prefix}/_router returns 404. The route catalog is invisible — agents cannot enumerate what's reachable under this prefix.

These are policy switches, not feature flags. They are independent: you can keep router introspection on while disabling the MCP server (e.g. for internal-only API surfaces that benefit from runtime discovery by your own apps but shouldn't be reachable to external agents). The data routes (/{folder}, /{folder}/{key}, /{folder}/_search) are never affected — REST consumers continue to work without disruption.

Toggle either flag through PATCH /v1/{env}/api/{api}/:

curl -X PATCH https://api.foxnose.net/v1/<ENVIRONMENT_KEY>/api/<API_KEY>/ \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{"mcp_enabled": false, "router_introspection_enabled": false}'

Typical governance scenarios:

When to use MCP vs. a hand-written integration

The MCP server is the lowest-effort path, but it isn't always the right one. A quick decision matrix:

In practice most teams end up using both: MCP for the user-facing assistant experience, direct SDK calls inside the app-specific orchestration layer. The two are not mutually exclusive — the same Flux API serves both.

Client compatibility

The MCP protocol version FoxNose targets is Streamable HTTP 2025-03-26 — see the MCP Server reference for protocol-level details.

What's next?

Connect your first client.

Read the protocol-level reference.

Manage the per-API toggles.