Skip to content
Markdown
ConceptForDeveloperWith Foxden Admin

The AI gateway ​

The AI gateway is the one MCP server in Foxden. It runs inside Foxden Admin at https://<your Admin address>/api/suite/mcp, and every assistant or agent connects to it, never to an app directly. Through it, one connection reaches every app the caller can use, acting as that caller. This page explains how it names, finds and runs tools, and how it decides what a caller may do.

One door, one sign-in ​

The gateway speaks MCP over streamable HTTP (POST only; a GET answers 405). It is stateless: it hands out an Mcp-Session-Id at initialize but keeps no session. It accepts a single JSON-RPC request per POST, not an array.

A caller proves who it is in one of two ways:

  • A person signs in with OAuth. The gateway's 401 carries WWW-Authenticate: Bearer realm="foxden", resource_metadata="…/.well-known/oauth-protected-resource/api/suite/mcp", scope="suite", and the rest is standard discovery: protected resource metadata, authorization server metadata at /.well-known/oauth-authorization-server, dynamic client registration at /api/oauth/register (or a client id metadata document), the consent page at /oauth/authorize, and the token endpoint at /api/oauth/token. PKCE with S256 is required, the code lives five minutes and works once, and the scope is always suite. The access token is a key that lasts until the person disconnects it; there is no refresh token.
  • An agent presents a key or a short-lived token of its own. See Give an agent its own identity.

The credential goes in Authorization: Bearer <token>. For a client that can only send fixed headers, x-api-key or x-auth-token work too. A token in the query string is never read.

How tools are named ​

Each app's tools appear under the app's prefix and an underscore:

PrefixApp
fennec_Fennec
arctic_Arctic
corsac_Corsac
pampas_Pampas
culpeo_Culpeo
cape_Cape
library_Library
admin_Foxden Admin (for people who hold Admin access)

So Fennec's list_deals is fennec_list_deals. The full list for each app, with every parameter, is in Agent tools. The tool names and parameters are a contract: they are not removed or renamed.

The gateway's own tools start with foxden_.

Finding and calling tools ​

A connection lists only the gateway's own tools by default, to keep the assistant's context small. Every app tool is still there:

  1. foxden_status says which apps the connection reaches, how many tools each has, and why any app is missing. It also carries each app's own guide (which call comes first, where ids come from). An assistant reads it before its first call into an app.
  2. foxden_find_tools finds tools by a few words ("void a signature request"). It answers with each match's name, arguments and effect, and the full schema of the best three. Pass tools: [names] for up to ten exact schemas.
  3. foxden_read runs a tool that only reads, and refuses anything else. foxden_call runs any tool.

foxden_search looks for a name in every app at once (people, companies, deals, meetings, documents, pages, conversations, forms, calls) when you do not know which app holds it.

To list every app tool at the top level instead, add ?mode=full to the address. Clients that stop at 128 tools should stay on the default.

Narrowing a connection ​

Query parameters on the address narrow what a connection lists and reaches. They grant nothing.

ParameterEffect
?apps=fennec,corsacOnly those apps (by prefix).
?toolset=salesA named set: sales (Fennec, Corsac, Pampas, Arctic), support (Culpeo, Cape, Library), admin, and job-sized Fennec sets fennec-sales, fennec-reporting, fennec-partners, fennec-admin. foxden_list_toolsets describes each.
?readonly=trueOnly tools that only read; the gateway's writing tools are hidden too.
?mode=fullEvery tool listed, not only the gateway's.

An unknown value is refused with a 400 that says what was wrong.

Batches ​

foxden_batch runs up to 25 calls in one request, five at a time. Each call is checked and recorded as if it ran alone, one failure does not stop the others, and the results come back in order with ok and the tool's own result. No call starts after 90 seconds. The gateway's own tools cannot run inside a batch.

Scheduling ​

foxden_schedule runs a call (or a batch) later, with runAt (a date and time, within a year), or on a repeat, with repeat (every 15 minutes to every 30 days, or at a time on chosen days in a time zone). Each run acts as the person who scheduled it, with the access they hold at that moment. foxden_list_scheduled lists your jobs and their last outcome; foxden_cancel_scheduled cancels, pauses or resumes one. A person may hold 50 active or paused jobs.

A run is refused, and the job paused, when the connection it was scheduled through has been disconnected, the person is suspended, an Owner's rule refuses it (a daily limit only skips that run), or the app refuses the person. Only the person who scheduled a job can resume it. Owners see every job under Workspace › Assistants › Scheduled.

Files ​

The gateway keeps files for each caller, for seven days: at most 50 MB each and 1 GB for the whole company. foxden_upload_file and foxden_write_file store one and return a fil_ id; a file an app's tool returns is stored the same way. foxden_read_file reads its text (PDF, Word, PowerPoint, Excel, CSV, JSON, Markdown, HTML), foxden_download_file returns its bytes, and foxden_list_files and foxden_delete_file manage them.

To give a file to any app's tool, pass "foxden-file:<id>" as that argument. The gateway swaps in the bytes after checking the file is yours, so the file never passes through the model. On a read-only connection, files an app returns are not stored.

Ready-made workflows ​

The gateway also offers MCP prompts that a client shows as commands, each a recipe across apps: deal to signed agreement, meeting to follow-up, weekly pipeline review, form responses to leads, account briefing, call to follow-up, and onboard a teammate. A prompt appears only when the connection reaches every tool it uses.

How access is enforced ​

The gateway holds no power of its own. On every request:

  1. It reads who the caller is and which apps they may reach right now: a live grant in Admin, an account in the app (a person signs in to the app once), and an app address the server knows. Access gained or lost shows on the next request.
  2. It routes the call by prefix and checks the address's narrowing and the Owner's rules: a paused connection, a person's assistant paused in one app, a tool taken offline, a daily limit on a tool.
  3. It mints a signed token that lives 60 seconds and works once, and sends the call to the app.
  4. The app checks the token and applies the caller's own level there. A person who can use Fennec gets what a person who can use Fennec may do; nothing the gateway does widens that.

Text an app returns (a meeting transcript, an email, a form answer) was written by someone else. The gateway tells the assistant to report such text and never follow instructions found in it.

A call that changes something may need confirming. Whether the gateway confirms for the person is the company's choice: see Choose whether assistants ask before acting.

The audit trail ​

Every call is recorded twice: by the app that ran it, and in Admin's log of assistant calls (the caller, the connection's key id, the tool, how it ended, its sizes and timing, never its arguments). Owners read it under Workspace › Assistants › Calls and Failures, and set rules under Rules. Connections made and removed, agent keys and the ask-before-acting setting are in Workspace › Activity. See Assistants.

Limits ​

LimitValue
Request body1 MB (larger for tools that carry a document)
One call55 seconds (120 for large documents and calls that carry a file)
Batch25 calls, 5 at a time
Files50 MB each, 1 GB per company, 7 days
Scheduled jobs50 per person, every 15 minutes at most

Each app also limits calls per person. When it does, the gateway answers with the app's name and how long to wait. A call that times out may still have finished: read the record before calling it again.

Foxden is open source under Apache-2.0.