--- url: https://docs.codefox.ai/connect/gateway.md --- # The AI gateway The AI gateway is the one MCP server in Foxden. It runs inside Foxden Admin at `https:///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](/connect/agent-identities). The credential goes in `Authorization: Bearer `. 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: | Prefix | App | |---|---| | `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](/reference/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. | Parameter | Effect | |---|---| | `?apps=fennec,corsac` | Only those apps (by prefix). | | `?toolset=sales` | A 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=true` | Only tools that only read; the gateway's writing tools are hidden too. | | `?mode=full` | Every 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:"` 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](/connect/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](/run-your-company/assistants). ## Limits | Limit | Value | |---|---| | Request body | 1 MB (larger for tools that carry a document) | | One call | 55 seconds (120 for large documents and calls that carry a file) | | Batch | 25 calls, 5 at a time | | Files | 50 MB each, 1 GB per company, 7 days | | Scheduled jobs | 50 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. ## Related pages * [Connect your AI assistant](/connect/ai-assistant) * [Give an agent its own identity](/connect/agent-identities) * [Agent tools](/reference/agent-tools/)