MCP servers
GitDB's built-in MCP server, adding your own MCP servers for Claude Code and Codex CLI, secrets, sign-in, Connect & check, and what each status means.
MCP servers give agents extra tools. In GitDB Desktop there are two kinds:
- GitDB's built-in server (named
gitdb). The app connects it for you on every thread that works in a GitDB repository — it's how agents reach the repository there. You don't set it up and can't edit it. - Your own servers — external MCP servers you add in the app. They're used on threads that work in a local folder, by Claude Code, Codex CLI, or both.
Threads in a GitDB repository use only the built-in server. The manager says so for those threads: "This is a GitDB workspace thread: external MCP servers are never loaded into it — only the embedded gitdb server."
Your server list belongs to the account you're signed in with (offline mode has its own list).
Open the MCP servers manager
- From a thread's ··· menu, choose MCP servers… (works for either CLI), or
- on a Claude Code thread, type
/mcpin the message box.
The manager opens as MCP servers: "External MCP servers for your Claude Code and Codex threads. The embedded gitdb server is managed by the app."
On a Codex CLI thread, /mcp opens a read-only view instead, MCP server status: "Read-only status of your MCP servers. To add, edit, enable or remove a server, choose MCP servers… from a thread's ··· menu."
The manager has three sections:
| Section | What's in it |
|---|---|
| Embedded | GitDB's built-in gitdb server, status only: "GitDB Desktop's own server. It is app plumbing, managed by the app — not editable here." |
| App-managed | The servers you add here. |
| From CLI config (read-only) | Servers already set up in your own Claude Code or Codex configuration, labeled with where each comes from. The app shows them but never changes them. |
Add a server
Click Add server and fill in the form:
| Field | What to enter |
|---|---|
| Name | A name for the server. |
| Transport | stdio (a command), HTTP, or SSE (Claude Code only). |
| Command and Arguments (one per line) | For stdio: the program to run, and its arguments. |
| URL | For HTTP and SSE: the server's address. |
| Timeout (ms, optional) | Leave empty to use the CLI's default. |
| Enabled | Whether the server is used. |
| Claude Code / Codex CLI | Which CLIs get the server. A new server starts with Claude Code on and Codex CLI off. |
| Secrets | Values the server needs but that you don't want visible — see below. |
Then click Save.
A few names and combinations aren't allowed, and the manager explains how to fix them:
gitdb, and any name starting withgitdb_, belong to GitDB Desktop's own server.- You can't have two servers with the same name.
- Codex has no SSE transport — turn the Codex CLI option off, or use an HTTP server.
- Codex accepts only letters, digits and
_ : @ / . -in a server name. - The command, arguments and URL can't contain
${…}placeholders. Write the literal value, and put anything secret in the server's secrets instead.
When changes take effect
- Claude Code threads that are already running pick up an added, edited, enabled, disabled or removed server right away.
- Codex CLI threads pick it up the next time the thread starts or resumes. The form reminds you: "Codex threads pick up this change on their next start or resume."
Secrets
For a stdio server, secrets are environment variables, one NAME=value per line. For an HTTP or SSE server, they're request headers, one Name: value per line — for example an Authorization header.
- Secrets are stored encrypted with your operating system's keychain. If the keychain isn't available, a server with secrets isn't saved at all.
- "Stored secret values are never shown — they only travel to the app once, when saved."
- When you edit a server that has secrets, choose Keep the stored secrets, Replace (type all the values again), or Clear.
Enable, disable, edit and remove
Each of your servers has Edit, Disable (or Enable) and Remove buttons. Remove asks you to click again ("Click again to remove") and deletes the server together with its stored secrets.
Statuses
Under each of your servers, the manager shows one line per CLI that uses it, and each line has a status:
| Status | Meaning |
|---|---|
| ● Connected | The server is connected. |
| ◐ Connecting / ◐ Starting | It's on its way up. |
| ⚠ Needs sign-in | The server needs you to sign in — see Sign-in. |
| ✕ Failed | It couldn't connect. The server's own error is shown next to it. |
| ○ Disabled | It's turned off. |
| ○ Not started / ○ Cancelled | Codex hasn't started it, or its start was cancelled. |
| ? Unknown | No status has been read yet. |
Next to each status is how fresh it is: live (read from the thread's running session just now), as of a time (the last status the app knew), or never checked. You can also expand View tools to see what a server offers.
Opening the manager never starts or connects anything by itself, so a status can be out of date. When it is, a line under the buttons says why — for example "This thread has no live session: statuses are the last known ones. Send a message to start one, or use Connect & check."
Connect & check
Connect & check "Connects your servers once to read their status". Use it to get a fresh status for every server, for example after adding one. On a thread that's running on Codex CLI, it also checks that thread's own servers, which starts and connects them once.
Reload config.toml servers re-reads the servers defined in your Codex configuration.
Sign-in
Some servers need you to sign in (OAuth). When a server needs it, its status is Needs sign-in and an Authenticate button appears:
- Click Authenticate. Your browser opens the server's sign-in page, and the manager says "Sign-in opened in your browser for" the server.
- Finish signing in in the browser. Claude Code finishes the connection on its own; Codex reports the outcome when it completes.
Authenticate needs an open thread to sign in through. On a Codex CLI thread, a server's first sign-in works like this: click Connect & check first, then Authenticate once it shows Needs sign-in. Codex's Authenticate also has an Advanced option, Client registration (Auto, CIMD or DCR); leave it on Auto unless your server's provider tells you otherwise.
On a Claude Code thread with a running session, each server also offers Reconnect and Clear sign-in. Clear sign-in "Affects every profile on this machine — the Claude CLI keeps MCP sign-ins per OS user, not per profile, so every profile here that uses this server is signed out of it too."
When a Codex server's sign-in expires
If a server refuses Codex's tool calls because its sign-in expired, the app tells you three ways:
- a message: "MCP server" name "needs you to sign in again", with an Open MCP servers button,
- a desktop notification, "Codex CLI needs MCP sign-in", if the app isn't the focused window, and
- a line on that server in the manager: "Sign-in expired — this server refused Codex's last tool call and asks you to sign in again.", with a Sign in again button.
When a server asks you something
An MCP server can ask you for input while an agent works. A window titled with the question (or "MCP server" name "needs input") appears and says the server "is waiting on this answer". Fill it in and click Submit, or click Skip to decline — the server is told you chose not to answer.
On Codex CLI threads, a server's tool call can also need your approval — see Permission and approval prompts.
Resources
On Codex CLI threads, a server's resources are listed under Resources. Click Read to see one, then Insert into composer to add it to your message.
On Claude Code threads, MCP resources can't be listed or read, and mentioning a resource in a message sends it to the model as plain text. The manager notes this on each Claude Code line.
Name clashes
If one of your servers has the same name as a server in your Claude Code or Codex configuration, both rows show a warning: "the two definitions collide." On Codex threads the two are merged, so settings from your Codex configuration can leak into your app-managed server. Rename one of them.
If your organization turns this off
Your organization can turn off external MCP servers on your computer. The manager then shows a notice that "External MCP servers are disabled by this machine's managed policy" and that "The manager is read-only". You can still see statuses, but you can't add, edit, enable, disable or remove servers, or sign in to them. GitDB's built-in server is not affected.