Using Gemini CLI with Gram-hosted MCP servers

Gemini CLI is Google’s open-source terminal-based tool that brings Gemini’s capabilities directly to your command line. Unlike web-based interfaces, Gemini CLI operates entirely in your terminal and has access to your current project folder, offering a lightweight and efficient way to interact with Gemini models from within your project.

When combined with Model Context Protocol (MCP) servers, Gemini CLI becomes even more useful. Using MCP servers, you can give Gemini access to your tools and infrastructure, allowing it to work with your APIs, databases, and other services through built-in MCP support.

This guide will show you how to connect Gemini CLI to a Gram-hosted MCP server using the example Push Advisor API from the Gram concepts guide. You’ll learn how to set up the connection, test it, and use natural language to perform vibe checks before you vibe code.

Find the full code and OpenAPI document in the Push Advisor API repository.

Prerequisites

You’ll need:

• A Gram account.
• Gemini CLI installed.
• Node.js version 18 or higher.

Installing Gemini CLI

You have two options to install Gemini CLI:

Option 1: Run directly with npx

npx https://github.com/google-gemini/gemini-cli

Option 2: Install globally

npm install -g @google/gemini-cli

Verifying the installation

Test that Gemini CLI is working:

gemini --help

If installation is successful, you’ll see Gemini CLI’s available commands and options.

Authenticating with Gemini CLI

When you first run gemini, you’ll be prompted to authenticate. You can sign in with your personal Google account to get free access to Gemini 2.5 Pro with generous usage limits (60 requests per minute, 1,000 requests per day).

Creating a Gram MCP server

If you already have a Gram-hosted MCP server configured, you can skip to connecting Gemini CLI to your Gram-hosted MCP server. For an in-depth guide to how Gram works and more details on how to create a Gram-hosted MCP server, check out the Gram concepts guide.

Setting up a Gram project

In the Gram dashboard, click New Project to start the guided setup flow for creating a toolset and MCP server.

Enter a project name and click Submit.

Gram will then guide you through the following steps.

Step 1: Upload the OpenAPI document

Upload the Push Advisor OpenAPI document, enter the name of your API, and click Continue.

Step 2: Create a toolset

Give your toolset a name (for example, “Push Advisor”) and click Continue.

Notice that the names of the tools that will be generated from your OpenAPI document are displayed in this dialog.

Step 3: Configure MCP

Enter a URL slug for the MCP server and click Continue.

Gram will create the toolset from the OpenAPI document.

Click Toolsets in the sidebar to view the Push Advisor toolset.

Configuring environment variables

Environments store API keys and configuration separate from your toolset logic.

In the Environments tab, click the “Default” environment. Click Edit and then Fill for Toolset. Select the Push Advisor toolset and click Fill Variables to automatically populate the required variables.

The Push Advisor API is hosted at canpushtoprod.abdulbaaridavids04.workers.dev, so set the <API_name>_SERVER_URL environment variable to https://canpushtoprod.abdulbaaridavids04.workers.dev. Click Update and then Save.

Publishing an MCP server

Let’s make the toolset available as an MCP server.

Go to the MCP tab, find the Push Advisor toolset, and click Edit.

On the MCP Details page, tick the Public checkbox and click Save.

Scroll down to the MCP Config section and copy the Public Server configuration.

The configuration will look something like this:

{
  "mcpServers": {
    "GramPushadvisor": {
      "command": "npx",
      "args": [
          "mcp-remote",
          "https://app.getgram.ai/mcp/canipushtoprod"
        ]
    }
  }
}

Use the Authenticated Server configuration if you want to use the MCP server in a private environment.

You’ll need an API key to use an authenticated server. Generate an API key in the Settings tab and copy it to the GRAM_KEY environment variable in place of <your-key-here>.

The authenticated server configuration looks something like this:

{
  "mcpServers": {
    "GramPushadvisor": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://app.getgram.ai/mcp/canipushtoprod",
        "--header",
        "Authorization: ${GRAM_KEY}"
      ],
      "env": {
        "GRAM_KEY": "Bearer <your-key-here>"
      }
    }
  }
}

Here’s what these configuration options do:

• "command" – The executable to run (in this case, npx).
• "args" – Array of command-line arguments.
• "env" – Environment variables for the server process (optional).
• "timeout" – Request timeout in milliseconds (optional, defaults to 600,000ms).
• "trust" – When true, bypasses all tool call confirmations (optional, defaults to false).

Connecting Gemini CLI to your Gram-hosted MCP server

Now we’ll connect Gemini CLI to your newly created MCP server.

Gemini CLI uses a settings.json configuration file to manage MCP servers. You can configure MCP servers in one of two files:

• Globally at ~/.gemini/settings.json.
• For a specific project at .gemini/settings.json in your project root.

Copy your public or authenticated MCP server configuration from Gram and add it to the .gemini/settings.json file.

Verifying the connection

Start Gemini CLI:

gemini

Then use the /mcp command to view the MCP server status:

/mcp

You should see GramPushadvisor and its available tools listed.

Press Ctrl + T to view detailed information about the server’s tools.

Testing the setup

Now test the connection by running a vibe check.

Ask Gemini a basic question like, “What’s the vibe today?”

Testing tool permissions

Ask Gemini to check if it’s safe to push code to production today:

Is it safe to push code to production today?

Gemini CLI will use the can_i_push_to_prod tool to check the current day. Before making the API call, it will ask for your permission to use the tool:

You can approve the tool call once, or choose to always allow this tool or all tools from the server to skip future prompts. Once approved, Gemini will make the API call and respond with the vibe check results:

Troubleshooting

Let’s go through some common issues and how to fix them.

Server not found

If Gemini CLI can’t find your server, press Ctrl + O to view the Debug Console.

If you see failed to start or connect to MCP server:

• Verify that the settings.json file is correct and matches the configuration from Gram.
• Check that the MCP server URL is accessible.
• Ensure you’re using the correct file path for your settings.

Authentication errors

If you get authentication errors:

• Verify your Gram API key in the dashboard under Settings > API Keys.
• Check that environment variables are correctly set in Gram.
• Ensure the Push Advisor API base URL is accessible.

Tool calls not working

If Gemini CLI isn’t calling the tools:

• Test the MCP server in the Gram Playground first.
• Check that the toolset includes the tools you want to use.
• Verify the environment is correctly configured with the required variables.
• Use /mcp in Gemini CLI to confirm the server lists the expected tools.

What’s next

You now have Gemini CLI connected to a Gram-hosted MCP server with vibe-checking capabilities.

Ready to build your own MCP server? Try Gram today and see how easy it is to turn any API into agent-ready tools.