Onehouse MCP server

Ask your coding agent about your Onehouse project, in plain words.

The Onehouse MCP server lets an agent such as Claude Code read your project — clusters, tables, flows, jobs, logs, usage and docs — and make a few changes. It is registered on your gateway as onehouse-external as soon as the gateway is enabled. You do not add it.

Claude Code  →  AI Gateway  →  onehouse-external  →  your Onehouse project

Everything runs as you, with your own Onehouse permissions. An agent cannot see or change anything you could not.

AWS projects only

The server signs each person in through the gateway's credential vault, which exists only on AWS. It is not available on Google Cloud projects.

What it can do

Tool	Does	Try asking
onehouse_read	Reads clusters, lakes, tables, flows, jobs and their runs, logs, sources, catalogs, access controls, the AI Gateway's setup, usage, audit logs, support tickets and Onehouse docs.	"List my running clusters"
onehouse_write	Starts, stops or restarts clusters. Opens and replies to support tickets.	"Stop cluster X"

Both tools are exposed from the start. Like any tool, they still need grants.

Give people access

On AI Gateway → MCP Servers, open onehouse-external:

1. Grant Connect to the people and groups who will use it, from Connect access.
2. Grant Call on onehouse_read, and on onehouse_write for those who may make changes.

You can hide either tool on the server's page. You cannot edit or delete the server itself; it is managed by Onehouse.

Connect your client

Add the gateway's tools to your client once — see Claude Code or Codex. The Onehouse MCP server comes with them.

Sign in once

1. In your client, ask: Call onehouse-external__authorize.
2. Open the link it returns and approve.
3. Reconnect the gateway's MCP server — in Claude Code, run /mcp and reconnect it.

The tools can take up to 5 minutes to appear. If they do not, reconnect again.

A service principal cannot complete this sign-in, so headless agents cannot use the Onehouse MCP server.

Troubleshooting

You see	Do
Only authorize, no other tools	Finish Sign in once, then reconnect.
"You have not authorized" or "session expired"	Open the link in the message and approve again.
"Access was removed by your admin"	Ask a project admin. Signing in again will not help.
"Response was too large"	Ask for less — one table, or a shorter time range.
401 when connecting	Your gateway token expired. With the oh CLI's helper this renews on its own; with a pasted token, get a new one.
mcp_tool_not_permitted	You hold no Connect on the server, or no Call on that tool. Ask a project admin.