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
- Codex
- Cursor
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:dip names every server that fell back this way.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
- Claude Code
- Codex
- Cursor (bearer token)
- claude.ai / Claude Desktop
With the default registration there is no step: Claude Code signs in with your The
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.
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 withoutdip’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
401with aWWW-Authenticate: Bearerheader 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/listcall 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. Analt_ API key requires the tenant-specific address; the shared address
refuses API keys:
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:
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
Related
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 withdip 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.