Guides

FAQ

Direct answers to the questions teams ask before and after connecting a service: networking, data, billing, failures, keys, protocol support and limits.

Short answers, each verified against the service. Where a longer explanation exists, the answer links to it.

#Networking and data

#Do I need a public IP or an open port?

No. Your service opens one outbound HTTPS connection to the gateway and keeps it open; the gateway sends calls down it. There is no inbound port, no ingress rule and no tunnel. If your service can make an outbound HTTPS request to the gateway address, it can serve tools.

#Where can the SDK run?

On anything with a process that stays alive: containers, Kubernetes, VMs, platforms that run long-lived services, or your laptop while you develop. It cannot run on request-scoped serverless platforms (for example AWS Lambda, Vercel functions or standard Cloudflare Workers), because the process is frozen between requests and the connection dies. If your API is serverless, run the agent as a small always-on worker that shares your service code.

#What leaves my network?

Only what you choose to return. A call's arguments pass from the gateway to your agent, and your handler's result passes back; your code, database, secrets and connection pools never leave. The gateway also holds the names, descriptions and schemas of your tools, resources and prompts, a hash of each key, and call metadata. See What we store.

#Does the gateway store the arguments or results of my calls?

No. Arguments and results pass through the gateway in memory and are not written to its logs. Logs record the tool name, time, duration, outcome, sizes in bytes, the key's label, the client's name, a request id, a trace id and the names of the arguments. Two exceptions you control: the error message of a failed call is stored (shortened to 300 characters), so keep secrets out of error messages; and a result is held in the gateway's memory for the number of seconds you set if you turn on caching for a tool.

#How long is data kept?

Call logs are kept for your plan's history window: 3 days on the Free plan by default, longer on paid plans. Optional process telemetry from the telemetry add-on (heap, CPU, event loop) is kept for a rolling 30 days. Agents are a live view only: they exist while connected and are not recorded as such. If you delete a project, its keys, call logs and usage history are deleted; if you delete your account (Delete account in the Danger zone of Settings), everything under it is deleted. See the Security guide for more.

#How much latency does the gateway add?

One extra hop: a call goes client, gateway, your service and back, so a call takes your handler's time plus the network round trips between those three. The Traces page splits a call's time into the gateway's part and your handler's part, so you can see where it went. It suits lookups and actions, not chatty high-frequency traffic.

#Calls and billing

#How are calls billed?

Only a billable call counts: a tools/call, resources/read or prompts/get that passed validation and was sent to your agent. It counts whether your handler succeeded, failed or timed out. These do not count: listing tools, resources and prompts; calls refused before reaching your agent (a bad key, an argument that fails schema validation, a rate limit, an allowance that is used up, no agent serving the tool); results the gateway answers from its cache; and playground runs.

Each plan includes a number of billable calls per UTC month (5,000 on the Free plan by default). At 80% the dashboard warns you; on a plan that blocks (Free), further calls are refused with Monthly allowance of 5,000 calls on the Free plan is used up. It resets on the 1st (UTC), or upgrade the plan., while listing stays free so a client can still connect and show the error. Paid plans exist and let calls continue past their included number, but no prices are published and billing is not live yet. See Plans and limits.

#What happens if my agent is down?

A client gets 503 with No agent connected for server "<project id>". (JSON-RPC code -32001), including for initialize and tools/list, so it sees a clear error instead of an empty server. Nothing else about your application is affected. When your agent starts it reconnects on its own and the project turns Connected again within seconds. If agents are connected but every one is disabled on the Agents page, the message is Every agent for server "<project id>" is disabled.

#What happens if the gateway is unreachable?

Your tools are unreachable from clients, and your application itself is unaffected. The SDK keeps trying to reconnect, waiting 1 second after the first failure and doubling up to 30 seconds with jitter, and resumes by itself.

#What if my agent dies while running a call?

The gateway notices the closed connection and fails the call at once with Agent disconnected before returning a result. It does not retry the call on another replica: delivery is at most once. If the caller retries, your tool should be safe to repeat. See Idempotency.

#How long can a tool take?

The default wait is 30 seconds. You can lower it for a project (1 to 30 seconds) in Project settings, not raise it. When it expires the client gets Request for tool "<name>" timed out after <ms>ms. For slower work, return a job reference and add a second tool to poll it.

#Can a tool stream its result?

No. A tool returns one result, and the client receives it in one piece. The reply to a client arrives as a one-event stream (that is only the HTTP framing), and there are no partial results or progress updates. Split long work into a start tool and a status tool.

#How large can a result or a request be?

A result is limited to 4 MB; a larger one fails the call with an error saying so. A request body from a client is limited to 4 MB. Return what the model needs: a trimmed object is better than a table dump. A result over 256 kB is also never cached.

#Does my handler know which client or user called?

No. A handler receives the arguments only, and acts with whatever authority your process has. Pass any user identity you need as an explicit argument, and use separate client keys (and tool allow-lists) to control which client can call which tool.

#Are there rate limits?

Yes, per project: a requests-per-minute budget on the MCP endpoint (600 a minute on the Free plan by default) and a limit on agent connection attempts (60 a minute). A refused request returns 429 with Retry-After. Both are listed in Plans and limits.

#Keys and access

#What auth models are there?

Keys: an agent key authenticates your service; a client key (or full key) authenticates an MCP client with Authorization: Bearer <key>. If the service you use has OAuth turned on for MCP clients, clients sign in with an access token instead, and agents still use agent keys. See Connecting clients.

#How do I rotate a key without downtime?

Create a new key of the same kind, deploy it, confirm the new key shows a Last used date, then Revoke the old one. There is no Rotate button. See Rotating a key without downtime.

#What happens when a key expires?

It stops authenticating, and an agent connected with it is disconnected shortly afterwards (within about half a minute). We email you 14 and 3 days before. Rotate before the expiry. See Expiry.

#Can I limit a client to some tools?

Yes. Give a client or full key an allow-list such as get_*. Tools outside it are absent from that key's tools/list and cannot be called. The list covers tools only, not resources or prompts, and cannot be edited after the key is created. See Tool allow-lists.

#Can I give a client read-only access?

Yes. Create a client or full key with Access set to Read only, or set Client access to Read only in Project settings to limit every client of the project. Such a client sees only the tools that read: those your agent labels readOnlyHint: true, or that you mark Read with Edit under Tools. A tool with neither counts as a write and is hidden. Resources and prompts are always readable. With OAuth, a token with only mcp:read is read-only. See Read-only keys.

#What do I do if a key leaks?

Revoke it on the project page. It stops working on the next request, and an agent connected with it is disconnected. Create a replacement, and check Activity and Logs for what the key did (the key's label is recorded on every call).

#Using the SDKs

#Which SDKs are available?

Node.js and Go are available now. Python, Java, C#, Rust and PHP are coming soon. You can also connect without an SDK by speaking the agent protocol directly; see Reference.

#Can I use several SDKs in one project?

Yes. A project's agents can be written in different languages, because they all connect with the project's key and speak the same protocol. Give every agent the same tools: the tool list a client sees comes from one of them, and each call goes to an agent that registered that tool. See Running replicas.

#Can I add a tool without redeploying?

Adding a tool means changing your code, so it needs a deploy (the new replicas register it when they connect). Without a deploy you can disable a tool, change the description models see, or cache its results from the dashboard. See Building tools.

#Does my agent have to be one process?

No. Run as many replicas as you like, up to your plan's connection limit (32 on the Free plan by default). Calls are spread across them, so keep state in a database. See Running replicas.

#Can I run an agent on my laptop?

Yes. Point it at the gateway with SPACEFIX_SERVICE_URL and a key. Use a separate project and key for development so your laptop never joins the rotation of production.

#How do I test without a client?

Use Try a tool on the project page or the Playground (runs are logged but not billed, and limited to a few a week per account), the MCP Inspector, or curl. See Connecting clients.

#Protocol

#Which MCP features are supported?

The endpoint is stateless: each request stands alone, there is no session, and the gateway never holds a stream open to the client. That is why it cannot ask the client for anything or push a notification; a client learns that your tools changed by listing them again.

#Which transport do clients use?

MCP over Streamable HTTP: the client POSTs JSON-RPC to /mcp/<project id> with Content-Type: application/json and an Accept header listing application/json and text/event-stream. GET and DELETE on the endpoint answer 405.

#Are pattern and format in my schema enforced?

No. They are advertised to clients so the model keeps the hint, but the gateway never runs them. Enforce them in your handler. Types, required fields, enums and numeric or length bounds are enforced before your handler runs. See Schemas.

#Operations

#Can several people use one account?

There is one sign-in per account today. Teams, seats and organizations are not available yet. Keep keys per deployment and per client so access can still be revoked individually.

#How do I see what my agents and clients are doing?

Agents shows live connections, Logs and Traces show each call, Usage shows counts and latency, and you can set alerts and webhooks. If you already use OpenTelemetry, the SDKs can emit spans and metrics into your own backend. See the Observability guide.

#Where do I start if something fails?

Press Check connection on the project page, then see the Troubleshooting guide. The exact text of every error is in the Reference.

#Next steps

• Quickstart if you have not made a first call yet.
• Concepts for the model behind these answers.
• Building tools and Running replicas before you go live.