Connectors
A connector is an MCP server: a program or web service that offers tools the model can call. Cloudflare, GitHub, Notion, Linear, Brave Search and Home Assistant have ready-made entries; anything else that speaks MCP can be added by its address or by the command that starts it. Once a connector is on, its tools sit beside Atelier’s own in Chat and Code, and in sub-agents.
Connectors belong to the backend, not to each person. An admin adds them, signs them in and sets what their tools may do; everyone on the server shares one connection and chooses per conversation which connectors it uses. If you run Atelier on your own computer, you are the admin. On a server, everyone can also add their own connectors, with their own keys, that only they use.
Add a connector
Section titled “Add a connector”Settings › Admin › Connectors (also Customize › Connectors, for admins) lists the connectors and has Add connector. Pick a service, or Custom (“Any MCP server, by its URL or the command that starts it”).
Ready-made entries
Section titled “Ready-made entries”| Entry | Connects to | Needs | Sign in with OAuth |
|---|---|---|---|
| Cloudflare | Workers, DNS, R2, D1 and the rest of your account, at https://mcp.cloudflare.com/mcp |
An API token. Grant only what you need; account tokens need “Account Resources: Read”, and IP-filtered tokens don’t work. | Yes |
| GitHub | Issues, pull requests, code search and Actions, at https://api.githubcopilot.com/mcp/ |
A personal access token (fine-grained works; classic ones need the repo and read:org scopes). GitHub’s hosted server may need Copilot on your account. |
No |
| Notion | Search, read and update the pages and databases shared with your integration | An integration secret, run with npx -y @notionhq/notion-mcp-server (needs Node.js, desktop app only); or sign in to Notion’s hosted server at https://mcp.notion.com/mcp |
Yes (the only way on a server) |
| Linear | Issues, projects and cycles, at https://mcp.linear.app/mcp |
A personal API key | Yes |
| Brave Search | Web, news and image search through Brave’s API | An API key, run with npx -y @brave/brave-search-mcp-server (needs Node.js, desktop app only) |
No |
| Home Assistant | Devices, sensors and automations, at <your address>/api/mcp |
The address of your Home Assistant (for example http://homeassistant.local:8123) and a long-lived access token from your profile; the “Model Context Protocol Server” integration must be enabled there |
No |
Each form asks for a Name (up to 64 letters, digits, - and _; it becomes part of every tool’s name, mcp__name__tool), then either the token
(with a link to where to create it) or Sign in with {service}, and then Add connector or Add and sign in. A pasted token is stored encrypted in the
secret store (Settings › Admin › Keys & secrets, with the id mcp-<name>), and the connector’s settings only refer to
it as ${secret:mcp-<name>}; it never appears in a settings file. On a server, Brave Search (which runs a program) is
disabled with “Only in the desktop app: it runs a program on your computer.”, and Notion offers only its sign-in.
Custom connectors
Section titled “Custom connectors”Custom asks for:
| Field | Meaning |
|---|---|
| Name | 1 to 64 letters, digits, - and _. Errors: “Give it a name.”, “Use up to 64 letters, digits, - and _.”, “There is a connector with this name already.” |
| Connects over | HTTP (the current MCP transport; if a server only speaks the older HTTP+SSE protocol, Atelier switches to it), SSE (that older streaming transport, chosen outright) or stdio (Atelier starts the server as a program; desktop app only, greyed out on a server). |
| URL (HTTP, SSE) | The server’s address, such as https://example.com/mcp. On an Atelier server these connectors run on the server, so in a browser localhost and 127.0.0.1 mean the server itself, and the field says so. Added in the desktop app, a new connector at localhost means that computer instead: it becomes your own connector, reached through that desktop app (an app’s local MCP server, such as Fusion’s). |
| Sign in with OAuth (HTTP, SSE) | For servers you sign in to instead of giving them a token; signing in starts once it is added. |
| Command and Arguments (stdio) | For example npx and -y, @scope/mcp-server, one argument per line. |
| Headers (HTTP, SSE) or Environment variables (stdio) | Name and value pairs. A value is plain text, a reference to a stored secret (${secret:id}) or to an environment variable of the backend (${NAME}), filled in only when connecting. The lock beside a value moves it into Keys & secrets when you save; names that look like credentials (token, key, secret, password, credential, auth) are locked automatically. Authorization: Bearer … keeps its scheme and stores only the token. |
The entry is saved as mcpServers.<name> in the backend’s global settings file, in Claude Code’s shape, so you can also
write it by hand:
{ "mcpServers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${secret:mcp-github}" } }, "notes": { "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/ada/notes"] }, "wiki": { "type": "http", "url": "https://wiki.example.com/mcp", "auth": "oauth", "disabledTools": ["delete_page"] } }}enabled (default true), disabledTools and preset are the other keys. A stdio server needs a command, an HTTP or
SSE server a url, and only HTTP and SSE servers can use "auth": "oauth".
Edit, switch off and remove
Section titled “Edit, switch off and remove”The list shows each connector’s name, type, status, how many of its tools are on, and a switch (Enable {name}) that turns the whole connector off for everyone. Click a row to open it. There, Test connection reconnects it and the ⋯ menu has Edit (the same form; the name, switches and tool settings stay), Sign out (OAuth connectors) and Remove. Removing a connector takes its tools out of every conversation and deletes its permission rules; the keys it used stay in Keys & secrets until you delete them.
Import from Claude Code and .mcp.json
Section titled “Import from Claude Code and .mcp.json”On the desktop app, Import from Claude Code reads the connectors Claude Code already has: your user and per-project
servers in ~/.claude.json and the .mcp.json files at the top of your folders on this computer. You choose which to
import; the credentials written into them move into the secret store, and a name that is already taken is marked “Already
added”. HTTP, SSE and stdio servers are imported; WebSocket and SDK servers have no counterpart and are skipped.
${VAR} references work as they do in Claude Code.
Atelier does not load a project’s .mcp.json by itself. Connectors are shared by everyone on the backend and are the
admin’s decision, so a file in a repository can’t add a server that runs on your computer. Import is also a one-time copy:
later changes to the file are not followed. On a server the button isn’t offered (“Importing from Claude Code works in the
desktop app, where its settings live.”); import them as your own connectors instead.
Your own connectors (on a server)
Section titled “Your own connectors (on a server)”On an Atelier server, Customize › Connectors has Your connectors for everyone, admins included: connectors only you use, with keys only you give. They sit beside the admin’s in + › Connectors, with the same switches per conversation. Your own desktop app’s backend has no such section; there, the connectors in Settings › Connectors are already yours.
Add your own asks for a Name, how it Connects over (HTTP, SSE or stdio), its URL (with Sign in with OAuth) or its Command and Arguments, and Headers or Environment variables. Every value is kept encrypted on the server as your own secret, never in your preferences and never shown again: editing a connector shows “Unchanged” for a value you leave empty. ⋯ has Edit, Sign in (OAuth ones) and Remove, which forgets its keys and sign-in.
Where each one runs:
| Connector | Runs |
|---|---|
| stdio (a program) | On your computer: the first one that is online, in the Atelier desktop app signed in to this server, and allows exactly that program. Adding it in the desktop app allows it there; on another computer, choose Run on this computer in its ⋯ menu. |
| HTTP or SSE at a public address | On the server. |
HTTP or SSE at an address on your computer or its network (localhost, 192.168.…, *.local) |
Through your desktop app, which allows that address when you add it there (Reach through this computer elsewhere). |
A program runs in your home folder with a small set of your environment (PATH, HOME, USER and the like) plus the
variables you gave it; a value like ${GITHUB_TOKEN} is filled in from your computer’s environment when it starts, never
the server’s. A connector can’t set variables that change which code runs (PATH, NODE_OPTIONS, LD_*, DYLD_*,
PYTHONPATH, PERL5LIB, npm_config_*, GIT_* and the like). Your computer keeps a fingerprint of the command, its
arguments and its variables’ names: if the connector changes, it says “It changed since you allowed it on {computer}:
allow it in Customize › Connectors in the Atelier desktop app there again.” What the program writes to its error output
stays in your connector’s log.
| Status | Meaning |
|---|---|
| Ready on {computer} | It runs on (or through) that computer. |
It runs a program on your computer: allow it in Customize › Connectors in the Atelier desktop app there. |
No computer of yours that is online allows it. |
Offline on {computer}: it runs there. |
The computer it ran on went offline; it starts again when one comes back. |
An admin's connector is also called {name}: rename yours. |
The admin’s connector of that name is used instead. A new connector can’t take an admin’s name. |
Import from Claude Code is offered in the desktop app signed in to a server: it reads Claude Code’s connectors on that computer (as above), shows each one’s exact command line, and adds the ones you choose as yours, allowed on that computer. The server can read those settings only for two minutes after you open the import there.
Let the assistant add one
Section titled “Let the assistant add one”Give the assistant an MCP server’s address in any conversation (“use the Fusion 360 MCP server at
http://127.0.0.1:27182/mcp”) and it asks to add it with AddConnector. The card shows the address and where it
goes; Add connector adds it, Don’t add (or Esc) doesn’t. It always asks, in every permission mode, Bypass
included. Once added, its tools work in the same conversation from the assistant’s next step, and the connector stays
with your others, where you can switch it per conversation, edit it or remove it.
| Where you are | Where it goes |
|---|---|
| The desktop app on Run on this computer | Settings › Connectors on this computer. |
| Signed in to a server, in the desktop app | Your connectors. An address on this computer or its network is reached through this desktop app, which allows it when you click Add connector. |
| Signed in to a server, in a browser | Your connectors. An address on a computer’s network can’t be reached from a browser: allow it in Customize › Connectors in the desktop app on that computer. |
It adds connectors without credentials: for a server that needs a key or a sign-in, add the key with Edit afterwards.
Sign in with OAuth
Section titled “Sign in with OAuth”Some services are signed in to instead of given a token. Adding Cloudflare, Linear or Notion offers Sign in with …, and a custom HTTP or SSE connector has the Sign in with OAuth switch.
- Choose Add and sign in (or Sign in on a connector that shows “Not signed in”). The service’s sign-in page opens: in your system browser on the desktop app, in a new tab on a web page. The connector shows “Waiting for sign-in”, with Open it again and Cancel. Atelier waits ten minutes.
- Sign in and allow access. The browser comes back to Atelier and the page says “Signed in”. On the desktop it returns to
a listener on
127.0.0.1that exists only for this sign-in; on a server, to/oauth/callbackon the address you reached the server at, which must be the same browser where you started, signed in to Atelier as yourself. - The connector connects. Every session now uses this one sign-in.
Atelier discovers the service’s authorization server, registers as a public client (PKCE, no client secret), asks only for access to that server’s resource, and checks that the answer comes from the server it started with. The sign-in page must use https (http is accepted for a loopback address only). The access and refresh tokens are kept as one encrypted secret (named “Sign-in for {name}”, an “OAuth token” in Keys & secrets) and refreshed on their own. If the service refuses the refresh, or the sign-in is revoked, Atelier forgets it and the connector shows Sign in instead of an error. Sign out in the ⋯ menu forgets the sign-in on purpose, and so does removing the connector, turning OAuth off for it or changing its URL.
| Message | Meaning |
|---|---|
This sign-in has expired or was used already. Start it again in Settings › Admin › Connectors. |
The one-use link was used or timed out. |
Finish signing in in the browser where you started it, signed in to Atelier as yourself. |
The return came from another browser or person. |
The sign-in page must use https, but it is http://… |
The service offered an insecure page. |
The server didn’t ask to sign in. |
The server doesn’t use OAuth, or already accepts the request. |
The sign-in was refused or didn’t finish. |
You declined, or the service returned no code. |
The sign-in came back from another authorization server than the one it started at. |
A mismatch the check refused. |
Tools and permissions
Section titled “Tools and permissions”Open a connector to see its Tools: each with its description, a Read-only badge when the server says the tool doesn’t change anything (a hint Atelier never trusts for permissions), and two controls.
- Use {tool} (the switch) keeps the tool from the model when off; the list shows the count (“3 of 5”).
- Always allow, Ask or Block decides when it may run:
| Setting | What happens when the model calls the tool |
|---|---|
| Ask (the default) | In a chat that has no sandbox or folder yet, a prompt asks you each time. Otherwise it follows the conversation’s permission mode: you are asked in Ask and Accept edits modes; in Auto mode, the reviewing model decides first and hands the decision to you when it is unsure. See Permissions. |
| Always allow | It runs without asking, in any mode except plan mode. |
| Block | It is refused, and the model is told the person’s settings rule it out. |
Behind the control is a permission rule on the tool’s name: Always allow adds mcp__{connector}__{tool} to Settings
› Admin › Code › Allow rules, Block adds it to Deny rules, and Ask removes both. You can write
mcp__github (every tool of a connector) or mcp__github__* yourself in those lists. When a prompt appears, Always
allow there makes a personal or per-project rule instead. In plan mode a connector tool runs only if the server marks it
read-only (and then follows its setting); the others are refused. Bypass mode allows everything that no Block rule
stops. Removing a connector removes its rules.
A connector’s rules cover every mode: they are the one permission that applies in Chat as well.
Choose connectors per conversation
Section titled “Choose connectors per conversation”In the composer, + › Connectors lists every connector with a checkbox and a count (“2 on”); one that can’t be used reads “Not connected” or “Switched off by an admin”. Unchecking a connector keeps its tools out of that conversation only; the choice is saved with the conversation, applies from its next message, and can be made before the first message of a new conversation. A sub-agent uses the connectors its parent has on.
When you change the selection mid-conversation the model is told once: “The github connector is now on
for this conversation; its tools are available.” or “… is now off for this conversation; its tools are gone.” (see
connector-on and connector-off in the context updates).
How tools reach the model
Section titled “How tools reach the model”Each tool becomes a tool named mcp__{connector}__{tool}; anything outside letters, digits, _ and - becomes _, and
the whole name is cut at 64 characters (a clash keeps the first). Its description is the server’s, cut at 2,048 characters
and escaped so it cannot pose as an Atelier instruction; for models with a small window only its first sentence is kept.
A conversation keeps the tool definitions it first saw, so a server that rewrites its tools mid-conversation doesn’t
break the cache; the set refreshes when tools are added or removed.
A conversation through ChatGPT Chat, the experimental desktop-only way to use a ChatGPT plan, lists
connector tools on request: the model sees only each tool’s name and the start of its description until it asks for the
ones it needs (ToolSearch, three at a time), which keeps the prompt small.
Results come back as text (up to 100,000 characters, then [Output truncated: showing 100000 of N characters.]; an empty
one reads (no output)). PNG, JPEG, GIF and WebP images are passed on as images; audio, other media and resource links are
summarized as a line. Anything that looks like a credential the connector was given is masked (••••) in its output,
errors and logs.
Questions from a connector
Section titled “Questions from a connector”A server can stop a tool call to ask you something. A form shows as a card titled “{connector} asks for information” with Submit, Decline and Cancel; a request to open a page shows “{connector} asks you to open a link” with the full address, Open link, Accept and Decline. Links never open by themselves. The call’s 60-second timer pauses while you answer.
Timing and limits
Section titled “Timing and limits”| Connecting | On first use, or when a status is asked for (opening the Connectors page or the message box’s Connectors menu). A connector that failed is tried again right then too, at most every 5 seconds, so one started after Atelier shows up without Test connection. Gives up after 30 seconds. |
| Retrying | After a drop or a failed connection: 1 s, 2 s, 4 s … up to every minute, and whenever a conversation starts. A connector that needs a sign-in waits for an admin instead. |
| Starting a conversation | A run waits up to 10 seconds for connectors still connecting, then starts without their tools. |
| One call | 60 seconds, then it is cancelled. Time spent waiting for your answer does not count. |
| Protocol | MCP 2026-07-28 where the server supports it, the earlier initialize handshake otherwise (the connector’s page says which: “MCP 2026-07-28” or “MCP 2025 or earlier”). Tool changes the server announces are followed. |
| Settings change | The connector restarts; switching tools on or off doesn’t reconnect it. |
Security
Section titled “Security”A connector gives the model hands outside Atelier, and what it returns is text from a third party.
- Prompt injection. A tool result, like a web page, can contain instructions. The model is told to treat connector output as data and to tell you when it tries to steer it, but that is a rule for the model, not a guarantee. Grant Always allow only to tools whose worst misuse you can live with, and leave write and delete tools on Ask or Block. In Auto mode, a call that is not allowed by rule is reviewed by another model; see Permissions.
- Shared credentials. A token or sign-in belongs to the backend and serves every person on it. Your own connectors’ keys and sign-ins are yours: nobody else’s sessions use them, and admins don’t see them.
- Programs. Only the desktop app starts stdio servers, and they run with your privileges: an admin’s on the desktop’s own backend, your own ones on your computer when its desktop app allows them.
Tokens are kept in the encrypted secret store and masked in output, errors and the connector log. See Security for the larger picture.
Troubleshooting
Section titled “Troubleshooting”A connector’s status is Connecting, Ready, Error, Off, Not signed in or Waiting for sign-in. Test connection on its page reconnects it. Settings › Admin › Developer has Connector logs (everything the connector printed and its connections and failures, last 200 lines, credentials masked) and Reload connectors and extensions, which reconnects every connector.
| Message | What to do |
|---|---|
Missing the secret "mcp-github". or Missing the environment variable NAME. |
The settings refer to a secret or variable that doesn’t exist. Add it in Keys & secrets, or fix the reference. |
This server runs a program on this machine (stdio), which only the desktop app does. … |
Use the service’s HTTP address instead, or run the desktop app. |
Can't reach 127.0.0.1:27182: nothing answers there (connection refused). |
Nothing listens at that address where the connector runs: start the app or server behind it, or check the port. On an Atelier server an admin connector runs on the server, where 127.0.0.1 is the server itself; the message says so, and a connector on your own computer belongs under Your own connectors. Other endings: the name doesn’t resolve, the host or network is unreachable, it took too long, its certificate isn’t trusted. |
The github connector is not connected: … |
It dropped. Atelier reconnects by itself; open its page and choose Test connection to try now. |
The wiki connector is signed out. An admin needs to sign in to it again in Settings › Admin › Connectors. |
Its sign-in was revoked or expired. |
The tool did not finish within 60 seconds and was cancelled. |
The server was too slow. Try a smaller request. |
The server ended the connection. / The connection closed. |
The server went away; it is retried with growing pauses. |
Signing in failed: … |
Read the rest of the message; start again with Sign in. |
| A token that worked stops working | The token expired or lost its scopes. Create a new one and use Rotate on its secret in Keys & secrets. |