FAQ and troubleshooting
Answers to common questions and fixes for common problems.
A server says "This server needs a credential"
The MCP server rejected Gatehouse's request, usually with a 401 or 403. Open Servers, click Edit on that server, paste a valid token into API token and save. Gatehouse reconnects right away. If the service expects a header other than Authorization: Bearer, use Other headers instead.
Claude Code shows Gatehouse as disconnected
Run /mcp in Claude Code, choose gatehouse and Reconnect. If it asks you to sign in again, choose Authenticate. This can happen after Gatehouse restarts or after an admin revokes your token.
My agent doesn't see a tool
Check, in order:
- The tool is On under Tools, not Needs review, Off or Changed · paused.
- Its server is turned on.
- A policy could allow or approve it for you. Use Policies → Test a call with your email.
- For per-person servers, you've connected your own account under Connect an agent.
Agents receive the updated tool list within seconds. If yours doesn't, reconnect it.
"You can't approve your own request"
Gatehouse never lets someone approve their own call, in any channel. Ask another approver. For a one-person trial only, set GATEHOUSE_ALLOW_SELF_APPROVAL=true.
A call says "expired"
Nobody decided before the approval timeout (5 minutes by default). Ask the agent to try again once an approver is around, or raise GATEHOUSE_APPROVAL_TIMEOUT_MS.
Slack buttons say I don't have an account
Gatehouse matches Slack users to Gatehouse people by email. Make sure your Slack email matches your Gatehouse email.
I'm locked out after too many passwords
Wait for the lockout to end (15 minutes by default) or ask an admin to Unlock you. Owners can also use the CLI to create a new account if every owner is locked out.
Gatehouse won't start: "requires a master key"
GATEHOUSE_ENV=production is set, which is the default in the Docker image, and no key was provided. Set GATEHOUSE_MASTER_KEY_FILE, GATEHOUSE_MASTER_KEY_COMMAND or GATEHOUSE_MASTER_KEY. See Self-hosting.
Does Gatehouse see my code or data?
Gatehouse sees the tool calls that pass through it and their results, because it has to check them. It stores calls in the audit log with secrets redacted, or only hashes with GATEHOUSE_AUDIT_ARGS=hash. It doesn't send anything anywhere you haven't configured.
Can I run more than one replica?
Not today. Gatehouse uses SQLite on a single volume. Run one replica with the Recreate strategy. A single instance handles a large team's agent traffic, since the gateway adds little work per call.
Which agents work?
Any MCP client that supports Streamable HTTP. Agents with OAuth support sign in through the browser. Others use a personal token in the Authorization header.