# How to add MCP servers to Google Antigravity (mcp_config.json)

Canonical: https://clawdocx.com/docs/antigravity-add-mcp-servers
Author: Theo Marsh
Difficulty: INTERMEDIATE
Published: 2026-02-24
Updated: 2026-10-24

> Add MCP servers to Google Antigravity's App, CLI and IDE: mcp_config.json paths, stdio and Streamable HTTP fields, OAuth, tool filters and timeouts.

To add an MCP server to Google Antigravity, put it in the `mcpServers` map of a file called `mcp_config.json`: globally at `~/.gemini/config/mcp_config.json`, or for one workspace at `.agents/mcp_config.json`. Each entry needs exactly one transport property, `command` for a local stdio server or `serverUrl` for a remote Streamable HTTP one, and the App, the CLI and the IDE all read that same schema. If the server you want is already in the MCP Store you never have to open the file: install it from Settings in the App, or from the agent side panel in the IDE, and edit the file only for custom servers and for the options no dialog exposes.

The steps and field names below are taken from Antigravity's own MCP documentation as it stood on 24 October 2026, when the current releases were Antigravity CLI 1.4.0 and Antigravity App 2.26.0. We did not install Antigravity to run them.

## Where does Antigravity look for mcp_config.json?

Two files, and the difference is scope rather than trust:

- **Global: `~/.gemini/config/mcp_config.json`.** The documentation says this one "applies to all your projects".
- **Workspace: `<workspace>/.agents/mcp_config.json`.** This one "applies only to that workspace".

Enabled plugins can also add MCP servers, so the servers an agent can reach are not always only the ones in these two files.

Two things worth knowing about those paths. The first is that they live under `~/.gemini/`, not under an Antigravity-specific directory, which is a legacy of the Gemini CLI that the `agy` CLI replaced. The second is that the MCP documentation gives both paths in `~` form and does not state a Windows location, so if you are on Windows, find the file through the IDE's **View raw config** rather than guessing at a path.

OAuth access tokens are kept separately, in `~/.gemini/antigravity/mcp_oauth_tokens.json`.

## What does an mcp_config.json entry look like?

The root object contains an `mcpServers` map in which each key is a unique server identifier. This is the documentation's own example, with one local server and one remote one:

```json
{
  "mcpServers": {
    "sqlite-explorer": {
      "command": "node",
      "args": ["/usr/local/bin/sqlite-mcp-server.js"],
      "env": {
        "SQLITE_DB_PATH": "/var/data/app.db"
      }
    },
    "my-remote-server": {
      "serverUrl": "https://api.example.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

Each entry must specify one transport property, and the rest are optional.

| Property | Type | Default | What it is for |
|---|---|---|---|
| `command` | string | required for stdio | The executable path or command name that launches a local stdio server |
| `serverUrl` | string | required for remote | The endpoint of a remote Streamable HTTP server. The docs add that "you can also use `url`" |
| `args` | string array | `[]` | Arguments passed to `command`, stdio transport only |
| `env` | object | `{}` | Environment variables injected into the local stdio server process |
| `cwd` | string | none | Working directory used when spawning a local stdio process |
| `headers` | object | `{}` | HTTP request headers sent with remote `serverUrl` connections |
| `authProviderType` | string | none | Set to `"google_credentials"` to attach Google Application Default Credentials |
| `oauth` | object | none | Manual OAuth 2.0 `clientId` and optional `clientSecret` for servers without Dynamic Client Registration |
| `disabled` | boolean | `false` | Suspends the connection without removing the entry |
| `enabledTools` | string array | none | Allowlist of tool names. When set, all other tools on that server are hidden |
| `disabledTools` | string array | `[]` | Denylist of tool names withheld from the agent |
| `timeoutSeconds` | integer | 180 per tool call, 300 to connect | Timeout for connecting and listing tools, and for each tool call |

Remote servers "must use the Streamable HTTP transport". The documentation is explicit that the legacy HTTP+SSE transport and the `httpUrl` field are not supported, so a config copied from an older agent that uses `httpUrl` will not work by renaming the product in your notes.

## How do you add a server on each surface?

The file is the same; the route to it differs.

**Antigravity App.** Click **Settings** at the bottom left, select **Customizations**, and find the **Installed MCP Servers** section. **Add MCP** connects you to the MCP Store, a searchable list; search or scroll to a server and click **Add**. From the same screen the trash icon uninstalls a server, the toggle disables or enables one, and there is a refresh button.

**Antigravity CLI.** Type `/mcp` in the prompt panel and press Enter to open the interactive **MCP Manager Overlay**. It shows live status rings for active, disconnected or loading servers, and it lets you reload server configurations or inspect connection logs without restarting. The CLI reads the same global and workspace files, so you can also edit them directly.

**Antigravity IDE.** Click the `…` at the top of the editor's agent side panel and select **MCP Servers**. Hover a store server and click **Install**. For a custom server, click **Manage MCP Servers**, then **View raw config**, and edit `mcp_config.json` there. Once installed, the server's resources and tools are available to the editor automatically.

The MCP Store is a convenience, not a security review. Antigravity lists direct integrations by category, with 15 servers under databases and storage, 17 under developer tools and CI/CD, 8 under frontend and design, 4 under security, and 33 under analytics, AI and cloud. An MCP server you install runs with whatever reach its configuration gives it, and being in the store is not a statement by us that it is safe to point at your production database.

## How do you authenticate an Antigravity MCP server?

Three routes, in rising order of how much you have to configure.

**Google Application Default Credentials.** Set `authProviderType` to `"google_credentials"` on a remote entry and Antigravity attaches your ADC. This needs ADC configured locally first:

```bash
gcloud auth application-default login
```

If you logged in previously, the documentation says to make sure your quota project is set:

```bash
gcloud auth application-default set-quota-project QUOTA_PROJECT
```

**OAuth.** For a server that supports Dynamic Client Registration, Antigravity handles OAuth automatically and the entry needs nothing but `serverUrl`. For a server that does not, supply `oauth.clientId` and optionally `oauth.clientSecret`, and register `https://antigravity.google/oauth-callback` as a redirect URI with your OAuth provider. To complete a login, open Agent settings with `Cmd` + `,` on macOS or `Ctrl` + `,` on Windows and Linux, go to the **Customizations** tab, click **Authenticate** next to the server, finish in the browser, then copy the authorization code back into the settings panel and click **Submit**. The server reconnects by itself afterwards. Expired tokens refresh automatically and invalid ones are removed.

**Custom headers.** For anything else, put the credential in `headers`, which is what the `Authorization: Bearer YOUR_API_TOKEN` line in the example above is doing. Remember that this is a plain JSON file on disk: a bearer token in `headers` is stored in clear text, so prefer `authProviderType` or `oauth` where the server supports them.

## How do you limit what an MCP server can do?

Two independent mechanisms, and you want both.

The first narrows the tool surface, inside the server's own entry. `enabledTools` is an allowlist and, per the documentation, "when set, all other tools on the server are hidden". `disabledTools` is a denylist. An allowlist is the better default for a server whose tool list you do not control, because a server that adds a tool next week does not silently gain it on your machine.

The second governs approval, and it lives in Antigravity's permissions system rather than in `mcp_config.json`. By default unconfigured MCP tools run in **Ask** mode, so Antigravity requests your approval before running one. Policy patterns let you widen that deliberately:

- `mcp(server/tool)` matches one tool on one server.
- `mcp(server/*)` matches every tool on one server.
- `mcp(*)` matches any MCP tool on any connected server.

Treat `mcp(*)` as what it is. It approves tools from servers you have not installed yet.

Finally, `disabled: true` suspends a server without deleting its configuration, which is the right way to park a server you are debugging rather than cutting it out of the file.

## How do you fix an MCP server that times out?

By default Antigravity waits up to 5 minutes for a server to connect and list its tools, and up to 3 minutes for each tool call. A call that runs longer fails with an error naming the server and the limit, in the form `MCP tool call to server "sqlite-explorer" timed out after 3m0s`.

`timeoutSeconds` in that server's entry changes both limits at once:

```json
{
  "mcpServers": {
    "sqlite-explorer": {
      "command": "node",
      "args": ["/usr/local/bin/sqlite-mcp-server.js"],
      "timeoutSeconds": 600
    }
  }
}
```

A positive value in seconds replaces both limits, so `600` allows a ten minute tool call. A negative value such as `-1` turns both off. Leaving it unset, or setting `0`, keeps the defaults.

One trap is documented and worth repeating: because the same value also limits how long the server has to connect, a small `timeoutSeconds` can stop a slow-starting server from connecting at all. If you set it low to fail fast on tool calls, you may have made the server unreachable instead.

## What changes if you are migrating from Gemini CLI?

Your servers move out of your preferences file and into a dedicated one. The migration documentation describes the old layout as servers "declared inline within `~/.gemini/settings.json`", and the new one as a standalone `mcp_config.json` profile at the two paths above. Its sample migration output reports the result in a line reading `mcpServers : 1 server definition migrated to mcp_config.json`, and reports `skipped (none detected)` when there was nothing to move.

If you port an entry by hand, the key to change is the URL one. The migration page lists `url` and `httpUrl` as the legacy schema keys and `serverUrl` as the current one. That is slightly stronger than the MCP reference page, which says `serverUrl` is the field to set and that `url` also works: the reconciliation is that `url` is still accepted while `serverUrl` is the key to write, and `httpUrl` is not supported either way.

Two other mismatches in the documentation are worth knowing before you copy an example:

- The migration page's sample entry puts an `env` block on a remote `serverUrl` server. The MCP reference page describes `env` as environment variables "injected into the local stdio server process" and marks `args` as stdio only. We follow the reference page: treat `env` as a stdio field and pass credentials to a remote server through `headers`, `oauth` or `authProviderType`.
- The SDK section says a Python application can connect `stdio`, `SSE` or `HTTP` servers programmatically, while the configuration documentation says the legacy HTTP+SSE transport is not supported. Read the SDK's claim as scoped to the SDK's own pipeline, not as a way to get an SSE server working through `mcp_config.json`.

## What should you check after adding a server?

Open the manager for your surface and look at the connection before you trust a tool call: `/mcp` in the CLI shows status rings and connection logs, and the App's and IDE's MCP screens have a refresh control. A server that is present in the file but not connected looks very similar to one that has no tools.

If you are coming to this from another agent, the shape of the problem is familiar but the file is not: our guide to [adding MCP servers to Codex](/docs/codex-add-mcp-servers) covers the same ground for a TOML config and a CLI that writes entries for you, and [what MCP actually is](/blog/what-is-mcp) is the background if the protocol itself is new to you. For Antigravity's other current facts, including which surfaces exist and how its skills work, the [Google Antigravity hub](/ai-agents/antigravity) is where we keep them, and the [MCP hub](/ai-agents/mcp) tracks the protocol and the agents that implement it.

## Frequently asked questions

**Where does Google Antigravity keep MCP server configuration?**

In a file called mcp_config.json, in one of two places. The global file is ~/.gemini/config/mcp_config.json and applies to all your projects. The workspace file is .agents/mcp_config.json inside the workspace and applies only to that workspace. The App, the CLI and the IDE all read the same standardized schema, so a server entry you write once has the same shape everywhere.

**Do you have to edit mcp_config.json by hand in Antigravity?**

No, if the server you want is in the MCP Store. In the App you go to Settings, then Customizations, then Installed MCP Servers, then Add MCP. In the IDE you open the agent side panel's more menu and choose MCP Servers, then Install. Hand-editing is for custom servers and for the fields no dialog covers: tool allowlists, timeouts, OAuth client credentials and environment variables.

**What transports does Antigravity support for remote MCP servers?**

Streamable HTTP only. The documentation states that remote MCP servers must use the Streamable HTTP transport, that the endpoint goes in serverUrl, and that the legacy HTTP+SSE transport and the httpUrl field are not supported. The Antigravity SDK page describes connecting stdio, SSE or HTTP servers programmatically, which is a different claim from the configuration file's.

**How do you stop an MCP server in Antigravity from exposing a particular tool?**

Use enabledTools as an allowlist or disabledTools as a denylist in that server's entry. The documentation says that when enabledTools is set, all other tools on the server are hidden. Separately, unconfigured MCP tools default to Ask mode, so Antigravity asks before running them unless a policy rule such as mcp(server/tool) allows them.

**Why does an Antigravity MCP tool call fail after three minutes?**

That is the default per-tool-call timeout. Antigravity waits up to 5 minutes for a server to connect and list its tools and up to 3 minutes for each tool call, and a longer call fails with an error naming the server and the limit. Set timeoutSeconds in that server's entry to raise both limits, or to -1 to turn both off.

**What happens to MCP servers when you migrate from Gemini CLI?**

They move out of your preferences file into a dedicated one. The migration documentation says servers were declared inline in ~/.gemini/settings.json and are now defined in a standalone mcp_config.json profile, and its sample output reports server definitions migrated to mcp_config.json. If you migrate a definition by hand, change the legacy url or httpUrl key to serverUrl.

## Sources

- [Google Antigravity Docs: MCP](https://antigravity.google/docs/mcp/)
- [Google Antigravity Docs: Gemini CLI migration](https://antigravity.google/docs/cli/gcli-migration)
- [Google Antigravity Docs: Changelog](https://antigravity.google/docs/changelog)