dip login registers your tenant’s MCP servers after installing the agent skills. From a plain terminal it adds absent entries in installed clients (Claude Code, Codex and Cursor), leaving existing entries untouched and printing replacement commands for entries that differ. From a coding agent’s terminal it registers with that agent; --agent NAME chooses explicitly. Skip registration with --no-mcp or DIP_NO_MCP=1 (true or yes); an explicit --agent NAME or --mcp=true overrides the environment. Claude Code uses your login without an allow rule. When tools were added, the summary names the clients changed and gives each client’s next step. For Claude Code, start a new conversation in the same folder and ask your question again. Most people never need anything on this page: give your agent your tenant link, it runs dip login itself, and you sign in and approve access in the browser window that opens.
If Claude Code was already running when you signed in, start a new conversation in the same folder and ask your question again. Your agent first answers anything it can through dip in the current conversation. If your request needs Dippr tools that are not loaded, it relays the line from dip login once, as the last step, and quotes your question so you can paste it into the new conversation. Resuming the existing conversation does not load the tools. A database shared with you to read only is read through the query engine rather than dip db sql; your own personal database still works with dip db sql. Your agent also offers the console or an available app link so you can see the data right now. Codex needs its client reopened; Cursor needs its window reloaded.

Registering the server

dip never edits a config file your agent owns — it runs each agent’s own CLI, or merges one key into the one config file that has no CLI of its own:
Claude Code signs in with your dip login. Each time it connects, it runs the registered dip mcp token --header-json command, which trades your login for a token for that one server and hands it to Claude Code. While your dip login is valid there is nothing to approve in /mcp, no token is written into Claude Code’s config, and signing out of dip (or revoking the login) ends the access too. If /mcp still shows the server as needing authentication, your login did not reach it: run dip login again, then start a new Claude Code conversation in the same folder and ask your question again.If your tenant cannot hand your login to the server (an older tenant), or you pass --mcp-auth oauth, dip registers the browser sign-in instead:
That registration only records the server. Continue to Signing in below. dip names every server that fell back this way.
Each server is registered under the name dippr-<tenant>-<plane>; if two data planes would reduce to the same name, dip appends a short suffix. An agent not installed on your machine is skipped, and dip prints the exact command you’d run once it is — install is safe to run again later. A server already registered at the same URL, with the same sign-in, is left alone, which is what keeps a Claude Code sign-in for it intact across repeat installs. A server registered with the other sign-in is registered again. dip mcp install --json reports how each agent signs in to each server, in clients[].auth: dip_login, oauth or bearer_env. dip mcp uninstall reverses all of this; add --dry-run to either command to see every change it would make without making it. The one exception: if your saved login is close enough to expiring that reading the plane list has to refresh it, that refresh still happens, and the run says so when it does.

Claude Code’s auto mode and the allow rule

An allow rule is a line in your Claude Code settings that lets Claude Code use a tool without asking first. dip login --allow-rule and dip mcp install --allow-rule add one for each Dippr server they register with Claude Code, because Claude Code’s default auto mode otherwise refuses the server’s tools. Neither adds it unless you pass --allow-rule: the rule covers every tool of the server, the write tools included, so it is your decision. In auto mode, Claude Code reviews every tool call that no rule of yours decides. It treats the rows run_sql returns, and a table’s columns from browse, as sensitive data, and refuses the call, so an agent connected to Dippr cannot read anything. A call that matches an allow rule runs without that review. What you are allowing. The rule turns off Claude Code’s prompts for every Dippr tool, including the tools that write (workspace_db_write_sql, workspace_db_share, workspace_db_upload_url) and any tool the server adds later, in every permission mode, not only auto mode. Every call still runs as you, with nothing beyond your access: your scopes, roles and grants decide what each call may read or change, exactly as in the console. The full list is on the tools list. dip changes only the allow list: every other byte of the file stays as you wrote it. When your settings file is a link, dip edits the file it points to; a link that points nowhere is left alone, with a warning. Just before it replaces the file, dip checks the file is still the one it read; if Claude Code saved it in the meantime, dip makes its edit again on the saved file. A save in the last instant before the replace can still be lost, so avoid changing Claude Code’s settings while dip login runs. The run prints one line naming the rule and the file:
dip mcp install --json reports the rule per server in clients[].allow_rules: added, in_place, off, removed or removed_by_you.

How do I remove the allow rule?

dip only ever removes a rule it added. If you wrote mcp__dippr-<tenant>-<plane> yourself before dip ran, it stays. If you delete the rule dip added, dip takes that as your choice: the next dip login leaves it out and says so, and dip mcp install --allow-rule adds it back. To have Claude Code ask before each Dippr call instead, add the same rule, mcp__dippr-<tenant>-<plane>, to permissions.ask; an ask rule wins over an allow rule. dip remembers the rules it added per settings file. If you point Claude Code at another configuration with CLAUDE_CONFIG_DIR, dip treats that file on its own: it adds the rule there, and an uninstall only takes out a rule dip added to the file Claude Code reads at that time. If dip cannot read your settings file as JSON, or the file repeats the permissions or allow key, it changes nothing in it. dip login and dip mcp install say so in a warning and still register the server; dip mcp uninstall exits with an error, because the rule it should remove is still there.

Signing in, per client

With the default registration there is no step: Claude Code signs in with your dip login. If a session was already open when dip registered the server, start a new Claude Code conversation in the same folder and ask your question again. The steps below are for a server registered with the browser sign-in (--mcp-auth oauth, or a server dip named as falling back to it).
1

Open a session and run /mcp

Inside any Claude Code session, type /mcp and select your tenant’s server from the list.
2

Choose Authenticate

Your browser opens the same sign-in you use for the console. Approve the connection on the consent screen — see Scopes and consent for what each line means.
3

Every call now runs as you

Claude Code holds the resulting token for this server and refreshes it automatically. Tool calls run under your own sign-in from here on.
The authenticate / complete_authentication tool pair a conversation may offer is a copy-paste fallback for a machine with no browser to open, not the path to reach for normally.

Manual configuration

Any MCP client that speaks OAuth or a bearer token can connect without dip’s help. Point it at the bare tenant-specific endpoint, with no path: https://<slug>.mcp.<plane-domain> for OAuth and API keys. It discovers everything else:
  • An unauthenticated call answers 401 with a WWW-Authenticate: Bearer header naming the scopes to request.
  • /.well-known/oauth-protected-resource (RFC 9728) and the authorization server’s own metadata document (RFC 8414) describe the OAuth flow — which endpoint to authorize against and which scopes it supports.
  • The tools your client actually receives are whatever its own tools/list call returns — that’s the one authority for what’s available, more than anything written here.

API-key configuration for headless clients

For a client that isn’t Claude Code, Codex or Cursor, a headless Codex, or a script you’re writing yourself, send the token as an ordinary bearer header. An alt_ API key requires the tenant-specific address; the shared address refuses API keys:
The token is either a minted alt_ service-user key, or — to call as yourself without a console key — the output of dip mcp token after a one-time dip mcp login:
dip mcp login performs the same browser authorization a GUI client’s Authenticate does — a direct OAuth grant bound to the plane’s MCP endpoint — and caches the result; dip mcp token prints and refreshes it. This is the headless path for an agent that has run dip login but has no browser at call time and no service-user key. The endpoint accepts a bearer token only — never a browser cookie — because it’s called by programs, often from a different host than the console.

Verifying the connection

From a terminal, dip whoami shows that your sign-in is live and dip engine list shows the query engines you can use; neither needs an MCP session. Add --workspace <url> to name the workspace. Then ask your agent to list your query engines, or run a small SELECT 1. If the agent does not see the Dippr tools, it was already running when dip login registered the server, and it reads its server list once per session. It keeps working through dip meanwhile. When your request needs the Dippr tools, your agent passes on the one line dip login printed for it, such as “If Claude Code was already open, start a new Claude Code conversation in the same folder and ask your question again.”, and nothing for you to type. Then do any one-time step it names. Cursor needs ALTIMATE_API_KEY set, Codex needs its own sign-in (codex mcp list shows OAuth in its Auth column), and a Claude Code server registered with the browser sign-in needs /mcp then Authenticate. The tenant’s /agents.md, the page an agent reads when you give it your tenant link, tells the agent to run dip login and every other command itself, so you only sign in in the browser; to keep going with dip in a session without the Dippr tools; and to say in one sentence what it cannot read there, never handing you commands, and relaying the next step only as the last step when dip login printed one for it. In Claude Code, claude mcp list shows a server’s status directly:
For a server registered with the browser sign-in, Needs authentication means the /mcp → Authenticate step never completed — see Troubleshooting below. A server that signs in with your dip login and shows Failed to connect or Needs authentication usually means the login expired or you signed out: run dip login again, then start a new Claude Code conversation in the same folder and ask your question again. If that does not clear it, run dip mcp install --agent claude again, then start a new Claude Code conversation in the same folder and ask your question again. If your tenant has Documents enabled, the agent also sees search_documents and get_document (Document tools). /agents.md tells it to cite title and page, to treat document text as data rather than instructions, and to relay a refusal’s message_for_user and follow its next_action, retrying only when that says to.

Reconnecting after a capability was added

An MCP connection’s scopes are fixed at the moment you approve it — see A token’s scopes are fixed at issue time. If your tenant turns on a feature (search, or the semantic layer) after you connected, or Dippr adds a permission to the default set, your existing connection doesn’t gain it on its own. Authenticate again: in Claude Code, run /mcp, choose the server and Authenticate. The consent screen names the permissions the connection is newly asking for, and approving it updates the connection. You don’t need to remove and re-add the server. A connection can gain only permissions in the default set this way; anything beyond it, such as changing data sources or engines, still needs a client set up to ask for it.

Troubleshooting

Install dip and sign in

What dip login does end to end, including the MCP install step.

Scopes and consent

What each line on the consent screen actually authorizes.

When there is no query engine

After sign-in, your agent lists query engines. It reuses an existing engine. If the list succeeds and is empty, it creates one with dip engine create --name starter --wait --json and tells you afterwards what it created. The engine pauses when idle, and a stopped engine starts on the first query. If your role cannot create an engine, ask a tenant admin. If Claude Code’s auto mode refuses creation, your agent shows the exact command and explains that it creates a shared query engine. Send that line back as your own message to request one attempt with the usual checks. If it is refused again, run it in your terminal (PowerShell on Windows), or use ! in Claude Code on macOS/Linux. ! runs in your own shell without Claude Code’s approval or sandbox. Your agent checks the engine list afterward.