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

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:

{
  "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.

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:

gcloud auth application-default login

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

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:

{
  "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 covers the same ground for a TOML config and a CLI that writes entries for you, and what MCP actually is 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 is where we keep them, and the MCP hub tracks the protocol and the agents that implement it.