Connect an AI agent

Connect Claude, Cowork, ChatGPT, Claude Code or Codex CLI to Dibbla in three steps, run the first three prompts, and revoke it again when you want to.

The Dibbla platform connector lets an AI agent inspect and operate your Dibbla resources through MCP. It is a streamable HTTP endpoint at https://mcp.<domain>/platform, protected by browser-based OAuth. You sign in as yourself, choose what the client may do, and never paste a Dibbla API token into the client.

Connect your assistant

The whole configuration is one URL, https://mcp.dibbla.com/platform, and one approval in your browser. Pick your assistant; each path ends the same way: Dibbla’s consent page opens, you approve, and the client stores the grant.

What is behind the steps

Everything around the URL — the skill your agent reads, the /dibbla:connect and /dibbla:deploy commands, the starter prompts a directory shows — is published in one public repository, dibbla-agents/dibbla-platform-connector. It contains manifests, skill text and prompts, and nothing that can run: no code, no install hook, and no credential of any kind. The endpoint is OAuth-protected, so every client performs its own authorization and no client is ever configured with a Dibbla API token.

A few things that only matter for some clients:

• Claude Code without the plugin. Add the server on its own with claude mcp add --transport http dibbla-platform https://mcp.dibbla.com/platform and authenticate from /mcp. Before you authorize, /mcp lists the server as needing authentication — that is the expected state, not a fault.
• Cowork through the plugin instead. Cowork can also install the same plugin from the same repository through its plugin settings: add the repository as a plugin source, install dibbla, and approve in the browser when the first tool is used. Cowork draws the app card, so an app your agent deploys appears in the conversation with its address and status.
• Claude on a Team or Enterprise plan. An owner may have to add the connector under Organization settings → Connectors before members can enable it in a conversation.
• ChatGPT is the surface where the app card shows your running app inside the conversation rather than a link to it. Custom connectors need a paid plan, and in a Business or Enterprise workspace an admin may have to allow custom connectors first.
• Codex CLI. codex mcp add writes the server to ~/.codex/config.toml; the name is yours to choose, but it is the name codex mcp login, codex mcp list and /mcp will use. Never add --bearer-token-env-var or a header: a static credential is exactly what this endpoint does not take.
• Any other MCP client discovers the authorization server from the protected-resource metadata the URL advertises. A loopback callback may use localhost, 127.0.0.1 or [::1] over plain http — both spellings of your own machine are accepted, so a client that binds the name rather than the address works without configuration. Any other callback host over plain http is refused; a callback on another machine has to be https.

Clients that publish a Client ID Metadata Document identify themselves by URL: the client_id is an https address, and Dibbla reads the document there each time you authorize. Nothing is registered, so connecting the same agent twice does not create a second client — the authorization server advertises client_id_metadata_document_supported: true in its metadata for clients that can do this. Clients that register dynamically instead keep working exactly as before; this is an addition, not a replacement. If a document cannot be fetched or is not valid client metadata, the authorization is refused with a message naming what was wrong with the document — a missing redirect_uris, an http callback, a document that declares somebody else’s client_id — so it can be fixed at the source.

Three things to ask for first

These work on a connection made a minute ago, with no knowledge of Dibbla and nothing installed on your machine. They cover the three things people arrive wanting: see what is there, read the code that is running, and change it and put it live. Paste them one after the other in a fresh session.

Using the Dibbla connector, tell me which Dibbla user and organization this connection acts as, what my role is, and whether it can write or only read. Then list my apps and say which of them are not running. Do not change anything.

Using the Dibbla connector, look at the code of my app that is running right now: find its files, read enough of them to understand it, and explain in a few sentences what it does and how it is put together. Quote the file and line numbers you based that on. Do not change or download anything.

Using the Dibbla connector, change the visible headline on my app to "Hello from my agent" and deploy it. Read the file that has it first, change only that file, and tell me the new address when the deploy is live — or which line of the build log it failed on.

The third one is the one worth watching. The agent reads the revision that is deployed, sends back only the file it changed, and follows the build until the app is live; on a surface that draws the app card you see the deploy’s steps tick along on their own. If your organization has turned deployment review on, the answer is that the deploy is waiting for somebody else to approve it — that is the policy working, and it is covered in Deploy from an agent.

The last two assume you already have an app. With none at all, ask instead: “Deploy a one-page site that says hello, and tell me its address when it is live.”

Connect with the Dibbla CLI instead

If you already use the dibbla CLI, it can authorize the connector for you and print the exact configuration for your client. It derives the MCP host from the active context, which matters on self-hosted and development installations: it keeps the browser login, the token audience and the MCP endpoint on the same server instead of silently pointing one part at production. Run dibbla update first if the commands below are missing.

1. Sign the CLI into the connector

   This opens a browser for authorization-code login with PKCE. The resulting grant is stored with the active CLI context; no access token is printed.

   Authorize

   Copy

   $dibbla mcp platform --login

2. Ask the CLI for your client's exact setup

   Choose the client you use. The command prints configuration for the active installation, so copy its output rather than replacing the host by hand.

   Claude Code Codex Gemini CLI

   Copy

   $dibbla mcp platform --client claude

   $dibbla mcp platform --client codex

   $dibbla mcp platform --client gemini

3. Complete the client's OAuth login

   Claude Code can add the printed remote server with claude mcp add, then authenticate from /mcp or claude mcp login dibbla-platform. Codex reads the printed block from ~/.codex/config.toml; run codex mcp login dibbla-platform, then inspect it with /mcp or codex mcp list. Gemini reads the printed JSON and handles OAuth when the server is first used.

   Each of these opens your browser and waits for the answer on a loopback callback on your own machine. Both spellings of that machine are accepted — http://localhost:PORT/... and http://127.0.0.1:PORT/... — so a client that binds the name rather than the address works without configuration. Any other callback host over plain http is refused; a callback on another machine has to be https.

4. Check the whole connection before using a tool

   The check verifies protected-resource discovery, the stored grant and token, MCP initialization, and the identity returned by the platform. It refreshes an eligible expired token automatically.

   Connection check

   Copy

   $dibbla mcp platform --check

When the check is green, ask your assistant:

Use the Dibbla platform connector to identify me, list my apps, and show me the current status of lumen. Do not change anything.

The assistant should report the same user and organization you approved in the browser, then find the Stage 1 app. A different identity or organization is a failed connection even if the transport itself is green.

A note for self-hosted and development installations

The client sections above name the hosted endpoint. On any other installation, substitute that installation’s own https://mcp.<domain>/platform — including in a client that connects from a vendor’s service rather than from your machine, where the MCP host has to be publicly reachable for the connection to be made at all.

ChatGPT on the web does not read a local Codex MCP configuration: a server added to ~/.codex/config.toml serves Codex CLI, and ChatGPT is connected separately as its own connector.

The agent gets its Dibbla knowledge from the server

There is nothing to install for the agent to learn how Dibbla works. The connector serves its own skill — a document about the connector itself: how to read the source of a running app, change one file and deploy it, follow a long operation, and work with databases, storage, secrets and workflows.

A client that supports MCP skills lists the skill on connect and loads it when it becomes relevant, the same way it would load one from your own machine. You do not copy it anywhere, and you do not update it: it is served by the same build that serves the tools, and it carries that build’s contract version, so the skill and the tool list an agent sees are always the same release. When Dibbla adds a capability, the next thing your agent reads already describes it.

A client that does not support skills is unaffected. It still receives a short brief when it connects, describing the order things happen in and what an answer means, and every tool still works exactly as before.

Your app appears in the chat, without you asking

When an agent creates an app for you, deploys it, or changes something, it shows you the app itself: a card in the conversation with the app’s name, its address, whether it is live, and — while a deploy is running — that deploy’s steps, which the card keeps up to date by itself until the app is live. You do not ask for it and you never name a tool. That instruction reaches the agent from the server: the brief it receives when it connects, and the skill it reads, both say that the card is shown after an app is created, right after a deploy is started, and after every change.

Whether you see a card or a paragraph depends on the surface, not on your account or your plan:

Nothing is missing on a client that cannot draw the card: the name, the address, the status and the build steps arrive in words instead. The one difference is that text does not move — the drawn card follows a running deploy on its own, while a written answer is the state at the moment the agent asked. There, the agent keeps following the deploy and tells you when it is live.

The card shows your app; it does not run it. To use the app you open it — the card has a button for that, and the address is on it — in a tab of its own, where it behaves exactly as it does for anyone else who visits it. That is the same on every surface: no chat host today lets a card load an address that is not the connector’s own, so a card that tried would show you an error page in place of your app. Yours will not.

Consent decides which tools exist

The first consent defaults to read access. Write access is separate and remains unchecked until you explicitly request and approve it. A client sees only the tools allowed by the resulting grant, so a missing write tool is often a narrow grant working as intended rather than a server fault.

If you later need broader access, clear or disconnect the client’s existing authorization and reconnect with the intended scopes. Approval is never widened silently. The platform capability contract renders every scope and capability from the same versioned contract used by the server.

Optional: understand one idempotent write

Keep the Stage 1 detour read-only. When you deliberately want to test write access later, use a new OAuth authorization and request only the restart scope. In Codex, add scopes = ["platform:apps:restart"] to the existing [mcp_servers.dibbla-platform] block, disconnect that server’s current authorization, then run codex mcp login dibbla-platform again. The scopes setting is part of Codex’s MCP configuration; it changes what Codex asks for, not what Dibbla approves automatically.

Other clients expose requested OAuth scopes in different places. Start a new authorization that requests the restart scope shown for platform.apps.restart in the capability contract. On Dibbla’s consent page, leave unrelated write access unchecked and explicitly approve restart access. The Dibbla CLI’s own --login uses the read defaults; it does not widen this client grant.

The platform_app_restart tool is synchronous and causes a real rolling restart of an app or one named service. It requires the target plus an idempotency key. If the exact same request is retried with the same key, the runtime returns the first result with replayed: true instead of restarting twice. Reusing that key for a different target fails as a conflict. It is not a durable or asynchronous operation.

This guide does not create a disposable app, and the tutorial’s lumen app is not a write-test fixture. Treat the sequence above as the behavior contract, not a command to run. Exercise it only when you already have an app that its owner has explicitly declared disposable and safe to restart: confirm that exact target, obtain the incremental write consent, make one restart request, and reuse its key only to recover from an uncertain response.

What an agent can and cannot do

Read the code that is running

An agent that is asked to change an app has to see it first, and for a long time the only way was to download the whole source archive onto a filesystem — which ChatGPT does not have, and which is a lot of bytes for a question about one function.

platform_files answers the three questions directly, over the same file-read access a download needs, against the revision that is actually deployed:

• action: glob — the paths in the app that match a pattern. A pattern with no slash matches by name at any depth, so *.py finds the Python anywhere in the tree, and src/**/*.ts narrows to a directory.
• action: grep — file, line number and the matching line for a search across the app. fixed searches for a literal string instead of a regular expression, and ignore_case folds case.
• action: read — a numbered window of one file. offset and limit say which lines, and the answer tells you when there are more.

All three take the app’s alias, and an optional ref to read an earlier deploy instead of the latest one — a revision from platform_deployments, or the one a finished deploy reported. Every answer says whether it was cut short by its limit, so a short list is never mistaken for the whole truth.

Things to ask a connected agent:

• “What does my-app do? Find its files and read enough to tell me.”
• “Where does my-app read DATABASE_URL?”
• “Show me lines 40-80 of src/server.ts in my-app.”
• “Did the login handler in my-app look different two deploys ago?”

Nothing is downloaded and nothing is written: these actions cannot change a file, and binary content is refused rather than returned as text. When an agent does need the whole app on a filesystem — to edit a checkout and deploy it — that is still a download, described in Deploy from an agent.

A deploy the agent then makes — a whole tree or a single changed file — obeys your organization’s deployment governance, exactly as a deploy from the Console or the CLI does. By default that means it rolls out: the app is live when the call comes back. If your organization has turned review on, the agent’s deploy does not go live — it succeeds as a pending deployment that a different authorized person approves in the Console, and the answer says so and links to it. That is the policy working, not the connector failing. Which model applies, and how to turn review on or off, is in Deploy from an agent.

Destructive actions: plan, approve, execute

Everything that destroys data follows one path, and it is the same path in every case: plan → human approval in the Console → execute. Deleting an app, a storage bucket, a database or a file works this way, and so does restoring a database — because restoring into a database that already exists replaces what it holds, and Dibbla cannot bring that back.

1. Plan. The agent calls platform_destructive_plan and names the resource — app, database, database_restore, file, storage_bucket, workflow or workflow_runs — and the target. Nothing changes. The plan comes back with an exact list of what will be destroyed — every table and byte, the volumes, the injected secrets, the dependent resources — a request_id that expires in ten minutes, and a Console link.
2. Approve. You open https://console.<domain>/connector/approvals/<request_id> in a browser, signed in as the same owner or admin who granted the connector its access. The page shows the bound organization, the client, the exact scope, the target and the effects, and asks you to type the resource’s name before the approval button unlocks. You can also reject, or revoke an approval you have already given.
3. Execute. The agent calls platform_destructive_execute with the same resource and the unchanged request_id, and nothing else. What is destroyed cannot be changed at this point; it was fixed when the plan was made, and resource only names the ledger the id belongs to.

Rules that hold for every one of them:

• There is no MCP approval tool. A model cannot approve its own plan, and no combination of tool calls adds up to one. The approval is a person in a browser or it does not happen.
• The request_id is a reference, not a password. Holding it authorizes nothing. The server re-checks your user, organization, role, connector client, grant, scope, the target and a digest of its live state at execution.
• A confirmation is single use, and it cannot travel. It works once, for that one resource, under that one plan. If the resource changed after you read the plan — a database grew, a file was replaced — execution is refused rather than performed against a description nobody approved.
• Plans expire. Ten minutes, then create a new one.
• Another organization’s resource is absent, not forbidden. Plan and execute both answer “no such resource”, so neither can be used to discover what exists elsewhere.

A restore plan reads a little differently from a deletion plan: it names the database, how many tables and bytes are about to be overwritten, and the source file it will load — or says plainly that nothing is overwritten, when the target database does not exist yet. Execute hands back a durable operation you follow with platform_operation (view chooses status, events, logs or output), because a large dump outlives a single call.

Deleting a file removes the file record and makes it unreachable to everything that names it, including database restore and file download. The stored bytes are content-addressed and shared with every other record holding the same content, so they are deliberately left alone.

File tools return a transfer link or ticket. If the MCP client cannot move the bytes directly, open the accessible browser fallback at https://console.<domain>/connector/transfers/<id>. The transfer broker talks to storage on your behalf; object-store credentials and presigned MinIO URLs are never exposed.

Giving the assistant a secret without pasting it

Sooner or later the assistant needs a credential only you have — a Stripe key, a mail provider’s token, a password for a service the app talks to. Do not paste it into the chat. Anything you type there is read by the model, kept in the client’s history, and often sent to a third party before it reaches Dibbla. The connector cannot take a secret’s value at all — there is no tool argument for one — so the assistant has exactly one way to get a secret into Dibbla, and it goes through you:

1. The assistant asks Dibbla, not you. It calls platform_secret_write with action=request, naming the secret and where it belongs — the organization, one app, or one service of an app — and writing two things for you: a short title for what the secret is, and a plain-language explanation of why the app needs it and where you find it. Dibbla answers a link and a request id, and nothing else. No value has moved. In the chat you get the link and a sentence like “open this, sign in and paste your Stripe secret key there — tell me when you’re done”.
2. You open the link and enter the value yourself. It points at https://console.<domain>/connector/secrets/<request_id>. You sign in with your ordinary Dibbla account and see one page: the assistant’s title and explanation, and beneath them the technical name, the app and service, the organization, and whether a value already exists there and will be replaced. You paste the value into a masked field and save. It goes straight from your browser to Dibbla over an encrypted connection, into the same secret store dibbla secrets set and the Console use.
3. The assistant only learns that you are done. It checks the request with action=status, sees completed, and carries on — configuring the app, redeploying, whatever it was doing — without ever having seen the value. Running services pick the new secret up on their next restart or deploy; saving the page restarts nothing.

What holds the page together:

• The link is for you, and only you. It opens only for the person the assistant was working for, signed in to that organization, with a role that may write secrets (owner, admin or developer). A colleague, another organization, or a stranger who finds the link sees nothing — not the app, not the secret’s name.
• It works while the assistant’s connection does. If you have disconnected the connector, or its access was revoked, the page refuses before you type anything and nothing is saved.
• It works once, for fifteen minutes. After you save, the same link cannot be used again — a second click or a replayed request changes nothing. A link that ran out, or a request you cancelled, is replaced by asking the assistant to request the secret again.
• Nothing on the page can be pointed elsewhere. The target was fixed when the assistant asked. The title and explanation are the assistant’s words, shown as plain text; if the page names the wrong app or the wrong secret, or the explanation asks for something that does not sound right, cancel it and tell the assistant.
• The value is never shown again. Not on the page after saving, not to the assistant, not in Dibbla’s logs. What the assistant can see afterwards is the same as for any secret: that the name exists, and when it was last rotated.

If an assistant asks you to paste a key anyway — into the chat, into a .env file for it to read, into an environment variable, or into any other tool field — say no and ask it to request the secret instead. An assistant working from an older copy of the tool list may still try the old set action; the server refuses it before anything is stored and points it at the request flow, so the worst case is one refused call. Reconnecting the connector gives it the current instructions. This applies to every kind of secret, including one the assistant would otherwise generate for the app: it asks, you enter.

The same page from a terminal. An assistant working in your terminal with the Dibbla CLI does the same with dibbla secrets request: it prints a link to this page, made with your own sign-in, and waits until you have saved.

An env var is not a way around it. A plain env var is readable — by you, your colleagues and the assistant — so the connector refuses an env write whose name or value looks like a secret, and one named like a secret the app already has. A person in the CLI or the console can confirm that a value only looks like a secret; the assistant cannot, and requests the secret instead. The same goes for what the assistant deploys: a dibbla.yaml whose environment: holds something that looks like a secret only warns a person, but an assistant’s deploy — and a proposal it wrote, whoever approves it — is refused.

Turning an env var into a secret. An env var that should have been a secret all along is promoted: the assistant calls platform_secret_write with action=promote, naming the app and the variable, and writes a title and an explanation as for a request. You get a link to the same page — dibbla env promote makes the same request from a terminal, and Make secret in the console’s environment editor does it too. Four things are different from an ordinary request:

• You enter a new value. The variable’s current value has been readable — in the app’s configuration, its release history, perhaps the chat — so it counts as exposed. Rotate it where it was issued (revoke the old key, create a new one) and enter the new one. The page refuses the unchanged value, and the request stays open for the new one.
• Saving removes the env var and restarts the app. Dibbla stores the secret, removes the env var from every workload of the app, and restarts the app so it reads the secret. No other save on this page restarts anything.
• It is for the whole app. An env var a deploy set is on every service, so the secret becomes the app’s: the assistant names no service, and a promotion for one service is refused. A variable that comes from the app’s dibbla.yaml cannot be promoted — the next deploy would put it back — so the line is removed, the app deployed, and a new value requested as a secret.
• Not while a deploy runs. Saving during a deploy of the app is refused with DEPLOY_IN_PROGRESS. Nothing is written and the request stays pending: save again once the deploy has finished, while the link lasts.

If the secret is stored but the env var could not be removed, the request still completes, and its status says env_var_remains. The page tells you what is left to do — remove the env var by hand, or, when the secret had not reached the app yet, keep the env var and promote again later — and the assistant does not set the env var again.

Troubleshooting

Disconnect and revoke access

You can cut a connected agent off yourself, at any time, without contacting support. It takes two steps, and they do different things — doing only one leaves you half-connected in a way that surprises people later.

1. Revoke the grant in your Dibbla account

   Open Connected agents in the account portal at https://app.<domain>/connected-agents — it is in the menu under your name, next to API Keys. Every agent holding access on your behalf is listed with the permissions it was granted, which organization the grant is for, and when it last renewed its access.

   Revoking one ends it on Dibbla’s side: the grant, every refresh token issued under it and the consent it stands on. This is the step that actually stops the agent, and it is the only one that does.

2. Remove the connector in the agent

   Then remove Dibbla from the client’s own connector or integration settings — Claude, ChatGPT, Codex, or whichever client you authorized.

   This step does not revoke anything on our side; it stops the client asking. Skip it and the connector stays configured in the agent, which will prompt you to sign in to Dibbla again the next time it tries to use a tool.

3. Revoke the CLI's grant, if you used it

   The CLI holds its own separate grant, listed alongside the others. You can revoke it from the portal like any other, or log out, which revokes it server-side first and then forgets the local record:

   Revoke access

   Copy

   $dibbla mcp platform --logout

An empty Connected agents list means no agent holds access to your Dibbla resources.

What happens to tokens already issued

Revoking a grant is one transaction, and it covers everything issued under it:

Two lifetimes are worth knowing even if you never revoke anything. A refresh token lives 30 days and is rotated on every use, so an agent you keep using stays connected without re-approving it — and an agent you stop using falls out of access on its own within 30 days. A dynamically registered client registration also expires after 30 days.

If a refresh token is ever presented twice, Dibbla revokes the whole token family and the grant rather than guessing which presenter was legitimate. At that moment the rightful holder and a thief are indistinguishable, so both lose access and you authorize again.

Report a connector you did not authorize

If Connected agents lists something you do not recognise, revoke it there first — that stops it on its next call — and then mail [email protected] with the client name and roughly when it appeared. Dibbla can revoke an individual grant, an individual client, or a whole registered client across every user, which is what an abuse report leads to.

Self-hosting the connector? See OAuth clients and the Helm feature gates.