Gemini CLI · MCP Server

Gemini CLI MCP Server: messaging, email and calendar

Q: Should I use url or httpUrl for a remote MCP server in Gemini CLI?

The documentation defines httpUrl as the streamable HTTP endpoint and url as an SSE endpoint. The gemini mcp add --transport http command writes url together with "type": "http", and both forms connect on current versions. If you write the file by hand, use httpUrl: a bare url without a type is read as SSE, the most cited cause of a Disconnected server.

Q: Where does Gemini CLI store MCP servers?

User settings in ~/.gemini/settings.json, project settings in .gemini/settings.json at the root of your project, both under the mcpServers key, and project settings override user settings. Note the default of the command: gemini mcp add writes to the project scope unless you pass --scope user.

Q: Can I add the Unipile server with one command instead of editing JSON?

Yes, and it is the recommended path: gemini mcp add --transport http --scope user --header "X-API-KEY: your-scoped-api-key" unipile "https://developer.unipile.com/mcp?branch=v2.0". The --header flag is repeatable and can sit anywhere in the command. Verified on gemini-cli 0.60.0.

Q: How do I keep my API key out of settings.json?

Write the header value as "$UNIPILE_API_KEY" or "${UNIPILE_API_KEY}". Gemini CLI expands environment variables in settings.json, headers included, so the project file can be committed without a secret and each developer exports their own scoped Account API key before launching gemini.

Q: My server shows Disconnected, what do I check first?

In order: the transport key (httpUrl for streamable HTTP, or url with "type": "http"), a project settings.json that overrides yours or the reverse, the folder trust (an untrusted folder disables every server), and finally a status shown as Disconnected while actions work, which comes from an optional ping in the specification. Run gemini mcp list, then /mcp inside a session.

Q: What does "No MCP servers configured." mean?

Gemini CLI found no mcpServers entry in the configuration it reads from the current folder. Check that the file is in ~/.gemini/ or in .gemini/ at the project root, that mcpServers sits at the top level of the JSON, and that the JSON is valid: a trailing comma is enough to have the file ignored.

One gemini mcp add command connects the Unipile MCP server. Your agent then builds LinkedIn, WhatsApp, email and calendar features into your project and tests every call on your Development application. Nothing to install or run locally.

Build Now Add Unipile to Gemini CLI

7-day free trial, no credit card.

~/.gemini/settings.json · unipile · Connected

Add calendar scheduling to my booking app.

Read endpointGET /v2/{account_id}/calendarsschema loaded

Added the availability route and the booking route. Events land on the calendar the user connected.

3 files changed · tested on the Development app

Describe the next feature…

Use case

Add LinkedIn, WhatsApp and email to your product from Gemini CLI

Add LinkedIn, WhatsApp, email or calendar to your product. Through the Unipile MCP server, Gemini CLI reads the API reference, writes the code in your stack and tests every request.

Connect the Unipile MCP server to Gemini CLIUnipile MCP connected

Select the channels you want to connectdeveloper.unipile.com/mcp

Connect all channels9 channels

LinkedIn/v2/{account_id}/chats

WhatsApp/v2/{account_id}/chats

Instagram/v2/{account_id}/chats

Telegram/v2/{account_id}/chats

Gmail/v2/{account_id}/emails

Outlook/v2/{account_id}/emails

IMAP/v2/{account_id}/emails

Google Calendar/v2/{account_id}/calendars

Outlook Calendar/v2/{account_id}/calendars

↑↓navigate spaceselect ↵connectone URL, one header

settings.json, user or project

Add the Unipile MCP server to Gemini CLI

The server is remote: one URL over streamable HTTP and one header, nothing to run locally. One command writes it to settings.json, user or project, and Gemini CLI connects at launch.

Before you start: Gemini CLI signed in, in a trusted folder, a Development application in the Unipile dashboard with a scoped Account API key, and one test account linked through Hosted Auth.

gemini mcp add, one linewrites settings.json for you

User settings~/.gemini/settings.json

Project settings.gemini/settings.json (default scope)

Key from an environment variable$UNIPILE_API_KEY in headers

User or project?The command defaults to project scope (.gemini/settings.json). Pass --scope user for every project on the machine.

terminal

# Register the hosted Unipile MCP server for every project (user scope) gemini mcp add --transport http --scope user \ --header "X-API-KEY: your-scoped-api-key" \ unipile "https://developer.unipile.com/mcp?branch=v2.0" # MCP server "unipile" added to user settings. (http) # Verify, or type /mcp inside a session gemini mcp list # ✓ unipile: https://developer.unipile.com/mcp?branch=v2.0 (http) - Connected

{ "mcpServers": { "unipile": { "url": "https://developer.unipile.com/mcp?branch=v2.0", "type": "http", "headers": { "X-API-KEY": "your-scoped-api-key" } } } }

{ "mcpServers": { "unipile": { "url": "https://developer.unipile.com/mcp?branch=v2.0", "type": "http", "headers": { "X-API-KEY": "$UNIPILE_API_KEY" } } } } // Committed with the repository: keep the key in the environment, not in the file.

{ "mcpServers": { "unipile": { "url": "https://developer.unipile.com/mcp?branch=v2.0", "type": "http", "headers": { "X-API-KEY": "${{UNIPILE_API_KEY}}" } } } } // export UNIPILE_API_KEY=your-scoped-api-key before launching gemini

Save the file and launch gemini in a trusted folder. Verified on gemini-cli 0.60.0.

httpUrl or url. Write httpUrl, or url with "type": "http": a bare url is read as SSE and shows Disconnected. Keep the key in $UNIPILE_API_KEY and leave the server's trust option unset, so Gemini CLI still confirms each action.

Verify the connection

1From the terminal, gemini mcp list shows unipile as Connected; Disabled means the folder is not trusted.
2Inside a session, /mcp lists every server with its state, and /mcp desc describes each action.
3In a chat, ask Using the Unipile MCP, list the endpoints for LinkedIn people search and their required parameters and expect real routes back.

Prompts, not glue code

Give your agent the prompt

Three integration jobs, each with the prompt to paste in Gemini CLI, the endpoints the agent runs on https://api.unipile.com with your X-API-KEY, and what lands in your project.

Gemini CLI · booking-appDevelopment app

Add calendar scheduling to my booking app: read each user's availability over a week and create the meeting on the calendar they connected, Google or Outlook.

Read endpointGET /v2/{account_id}/calendars/{calendar_id}/eventsschema loaded

Run requestPOST /v2/{account_id}/calendars/{calendar_id}/events201 Created

Added GET /api/availability (events over the requested window, busy slots computed server-side) and POST /api/bookings, which creates the event with attendees on the user's calendar and stores the returned event ID. Time zones are taken from the calendar. Created a test event on the Development app.4 files changed · tested on the Development app

Availability and event creation on the calendar your user connected

Google Calendar and Outlook Calendar share the same calendar routes. Gemini CLI reads the calendar, event and attendee schemas, writes the availability logic and the booking route, and creates one event on a test calendar.

Endpoints the agent uses

GET/v2/{account_id}/calendarsGET/v2/{account_id}/calendars/{calendar_id}/eventsPOST/v2/{account_id}/calendars/{calendar_id}/events

See every channel on the Unipile MCP server

Gemini CLI · support-inboxDevelopment app

Our inbox already syncs LinkedIn and WhatsApp with Unipile. Add Instagram and Telegram with the same thread model and the same reply endpoint.

Search endpoints"chats messages attendees"3 matches

Run requestGET /v2/{account_id}/chats200 OK

No new model: Instagram and Telegram chats come through the same chat and message routes, so the sync job now iterates over every connected account regardless of provider, and the reply endpoint sends on the chat's own account. Added the two provider badges and ran the sync on the Development app with one Instagram and one Telegram test account.3 files changed · 4 channels in one list

Same routes, two more channels, no new model

Every messaging provider uses the same chat routes, so extending an inbox means linking accounts through Hosted Auth. The agent checks the provider-specific fields and keeps your thread model unchanged.

Endpoints the agent uses

GET/v2/accountsGET/v2/{account_id}/chatsGET/v2/{account_id}/chats/{chat_id}/messagesPOST/v2/{account_id}/chats/{chat_id}/messages/send

Build a unified inbox with an agent

Gemini CLI · crm-appDevelopment app

Review my current Unipile integration for incorrect IDs, unsafe retries and calls that should be webhooks, and propose the fixes.

Read endpointPOST /v2/{account_id}/chats/{chat_id}/messages/sendschema loaded

Read endpointPOST /v2/webhooks/endpoints/schema loaded

Found three issues: the send call used the workspace's first account instead of the chat's account; the retry wrapper re-sent messages on a timeout; the inbox polled the chats route every 30 seconds. Proposed patches: account ID taken from the chat, retries limited to reads, a webhook endpoint for message events. Applied and verified on the Development app.3 findings · 3 patches · verified on the Development app

An audit against the real contract, not against memory

The agent compares your code with the real request and response schemas: account fields, idempotent calls, polling loops that webhooks replace. The review lands as a diff, tested on your Development application.

Endpoints the agent uses

GET/v2/accounts/{account_id}POST/v2/{account_id}/chats/{chat_id}/messages/sendPOST/v2/webhooks/endpoints/GET/v2/webhooks/conversations/

Wire webhooks with an agent

A Development application first Give Gemini CLI a scoped key from a Development application, kept apart from Production.

Test accounts, real requests The agent runs requests on test accounts, on behalf of the authenticated user who linked them, within each provider's limits.

Validate each flow Check the connect flow, one read and one write per feature, and a webhook delivery.

Then switch to Production Nothing touches your users' accounts until you switch the key. See security and compliance.

Troubleshooting

Common errors and what they mean

What gemini mcp list and /mcp show when an entry is not right, and the fix for each.

No MCP servers configured.

Put mcpServers at the top level of ~/.gemini/settings.json or .gemini/settings.json, with no trailing comma.

Disconnected

Use httpUrl, or url with "type": "http", since a bare url is read as SSE.

Disabled, folder untrusted

Accept the trust prompt at first launch, or run gemini trust in the project.

Added in the wrong place

Add --scope user to gemini mcp add, which defaults to the project file .gemini/settings.json.

401 Unauthorized on requests

Connected does not check the key: export the variable named in headers and use a scoped Account API key.

Timed out

Check the network, any proxy and the URL before setting timeout on the entry.

6000+ Companies Innovating with Unipile

Trusted by industry leaders

1 API

Streamline operations for all major communication channels

2 Days

Achieve live integration quickly with minimal setup

30%

Reduction in maintenance efforts and resources

Built-In Security and Compliance

Enterprise-grade protection for your data and workflows Learn more about our security

SOC 2 Type II

Certified

Independently audited security controls ensuring data protection and operational integrity.

GDPR

Compliant

Full compliance with European data protection regulations for user privacy.

99.9%

Platform Uptime over the last 24 months

24/7

Global Support with high-performance API

Gemini CLI MCP server FAQ

The questions people actually type: httpUrl or url, where settings.json lives, one command instead of JSON, keeping the key out of the file, Disconnected, No MCP servers configured, the VS Code extension and keys.

The documentation defines httpUrl as the streamable HTTP endpoint and url as an SSE endpoint. The gemini mcp add --transport http command writes url together with "type": "http", and both forms connect on current versions. If you write the file by hand, use httpUrl: a bare url without a type is read as SSE, the most cited cause of a Disconnected server.

User settings in ~/.gemini/settings.json, project settings in .gemini/settings.json at the root of your project, both under the mcpServers key, and project settings override user settings. Note the default of the command: gemini mcp add writes to the project scope unless you pass --scope user.

Yes, and it is the recommended path:

gemini mcp add --transport http --scope user --header "X-API-KEY: your-scoped-api-key" unipile "https://developer.unipile.com/mcp?branch=v2.0"

. The --header flag is repeatable and can sit anywhere in the command. Verified on gemini-cli 0.60.0.

Write the header value as "$UNIPILE_API_KEY" or "${UNIPILE_API_KEY}". Gemini CLI expands environment variables in settings.json, headers included, so the project file can be committed without a secret and each developer exports their own scoped Account API key before launching gemini.

In order: the transport key (httpUrl for streamable HTTP, or url with "type": "http"), a project settings.json that overrides yours or the reverse, the folder trust (an untrusted folder disables every server), and finally a status shown as Disconnected while actions work, which comes from an optional ping in the specification. Run gemini mcp list, then /mcp inside a session.

Gemini CLI found no mcpServers entry in the configuration it reads from the current folder. Check that the file is in ~/.gemini/ or in .gemini/ at the project root, that mcpServers sits at the top level of the JSON, and that the JSON is valid: a trailing comma is enough to have the file ignored.

This page covers Gemini CLI in the terminal, and the configuration described here is the settings.json read by the CLI. The extension has its own MCP settings in VS Code; check its documentation before assuming the file is shared.

The server answers without a key when the agent only reads the API specification. To run real requests, create a Scope in your Development application, assign the test accounts, and generate a scoped Account API key for that Scope. Never give an MCP client a Service key or a global Account key.