> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Move your MCP servers

> Add your MCP servers to Gloo Code, with copy-and-paste conversions from Claude Code .mcp.json and Codex config.toml.

MCP servers are one part of your setup you re-enter in Gloo Code. They go in the `mcp` section of `gloocode.json`, and each conversion takes a minute or two.

## Where the config lives

| Scope | File |
| - | - |
| Just this project | `gloocode.json` at the project root |
| All your projects | `~/.config/gloocode/gloocode.json` |

Both files allow comments. Servers in a project's `gloocode.json` apply after you trust the folder, and after you trust the folder, Gloo Code asks you to approve each server the project defines. If a server's command or URL changes, it asks again. Type `/mcps` inside Gloo Code to see your servers.

## The format

Each server is an entry under `mcp`, named by its key. There are two types.

**Local (runs on your machine)**

```json gloocode.json theme={null}
{
  "mcp": {
    "fs": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/repo"],
      "environment": { "LOG_LEVEL": "info" },
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

* `command` is a single array that holds the program and all of its arguments.
* `environment` holds environment variables for the process.

**Remote (over HTTP)**

```json gloocode.json theme={null}
{
  "mcp": {
    "api": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer {env:API_KEY}" },
      "enabled": true,
      "timeout": 30000
    }
  }
}
```

* `url` is the server's address. Gloo Code connects over Streamable HTTP and falls back to SSE.
* `headers` are sent with each request.

Other keys:

* `enabled`: set to `false` to keep a server in the file without loading it.
* `timeout`: milliseconds allowed for connecting, listing tools, and each tool call.
* `oauth`: for remote servers that sign in with OAuth, run `gloocode mcp auth <name>` and follow the browser prompt. `gloocode mcp auth list` shows what is signed in.

### Keep secrets out of the file

Write `{env:NAME}` anywhere in the config and Gloo Code fills it from your shell environment. Use `{file:path}` to read a value from a file.

```json gloocode.json theme={null}
{
  "mcp": {
    "api": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer {env:API_KEY}" }
    }
  }
}
```

### Add a server with the wizard

Prefer prompts to editing JSON? Run `gloocode mcp add`. It asks whether the server is for this project or all projects, what to name it, whether it is local or remote, and whether it uses OAuth. `gloocode mcp list` shows what you have.

> [!NOTE]
>
> Notion and Linear are built into Gloo Code as connectors, so give a server of your own a different name than `notion` or `linear`.

## From Claude Code

A Claude Code `.mcp.json` uses `mcpServers`. In `gloocode.json` the key is `mcp`, a local server's `command` and `args` merge into one array, `env` becomes `environment`, and `${VAR}` becomes `{env:VAR}`.

```json .mcp.json theme={null}
{
  "mcpServers": {
    "fs": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
      "env": { "X": "${X}" }
    },
    "api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}
```

```json gloocode.json theme={null}
{
  "mcp": {
    "fs": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/repo"],
      "environment": { "X": "{env:X}" }
    },
    "api": {
      "type": "remote",
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer {env:API_KEY}" }
    }
  }
}
```

| `.mcp.json` | `gloocode.json` |
| - | - |
| `mcpServers` | `mcp` |
| `command` plus `args` | `"type": "local"` and one `command` array |
| `env` | `environment` |
| `"type": "http"` or `"sse"`, `url` | `"type": "remote"`, `url` |
| `${VAR}` | `{env:VAR}` |
| `headers` | `headers` |

## From Codex

In Codex each server is a `[mcp_servers.<name>]` table. Convert it to an entry under `mcp`.

```toml ~/.codex/config.toml theme={null}
[mcp_servers.docs]
command = "npx"
args = ["-y", "some-mcp"]
env = { TOKEN = "x" }
startup_timeout_sec = 20
```

```json gloocode.json theme={null}
{
  "mcp": {
    "docs": {
      "type": "local",
      "command": ["npx", "-y", "some-mcp"],
      "environment": { "TOKEN": "x" },
      "timeout": 20000
    }
  }
}
```

| `config.toml` | `gloocode.json` |
| - | - |
| `[mcp_servers.<name>]` | `mcp` entry named `<name>` |
| `command` plus `args` | `"type": "local"` and one `command` array |
| `env` | `environment` |
| `url` | `"type": "remote"`, `url` |
| `bearer_token_env_var = "T"` | `"headers": { "Authorization": "Bearer {env:T}" }` |
| `startup_timeout_sec = 20` | `"timeout": 20000` (milliseconds; also limits each tool call, so raise it if tools run long) |

To keep a secret out of the file, export it and use `{env:TOKEN}`.

## Check that it worked

**1. Export your secrets**

Set any variables you referenced with `{env:...}` in your shell before starting Gloo Code.

**2. Start Gloo Code and trust the folder**

Run `gloocode` in the project. Approve the folder and any project MCP server when asked.

**3. List your servers**

Type `/mcps` in a session, or run `gloocode mcp list` in a terminal.

**4. Try a tool**

Ask the agent to do something your server enables, such as "List the files the filesystem server can see".

## Next steps

> **[Migration checklist](/gloocode/migrate/checklist)**
>
> A copy-and-paste checklist for your first day.

> **[From Claude Code](/gloocode/migrate/from-claude-code)**
>
> Skills, commands, and day-to-day shortcuts.

> **[From Codex CLI](/gloocode/migrate/from-codex)**
>
> AGENTS.md and day-to-day equivalents.

> **[Ask Gloo Code](/gloocode/ask-gloocode)**
>
> Ask Gloo Code about any config key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.