Using Claude Desktop with Gram-hosted MCP servers

Claude Desktop is Anthropic’s standalone AI assistant application that supports MCP through a JSON configuration file.

When combined with Model Context Protocol (MCP) servers, Claude Desktop becomes even more powerful. Using MCP servers, you can give Claude access to your tools and infrastructure, allowing it to work with your APIs, databases, and other services.

This guide will show you how to connect Claude Desktop 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.

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

Prerequisites

You’ll need:

• A Gram account.
• Claude Desktop installed.

Creating a Gram MCP server

If you already have a Gram MCP server configured, you can skip to connecting Claude Desktop to your Gram-hosted MCP server. For an in-depth guide to how Gram works and more details on creating 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).

Now that you have your MCP server configuration, you can connect it to Claude Desktop. We’ll look at two ways to do this:

1. Using the MCP configuration file in Claude Desktop.
2. Using the Claude Connectors feature to connect directly to your Gram-hosted MCP server.

Connecting Claude Desktop to your Gram-hosted MCP server using the MCP configuration file

Step 1: Access Claude Desktop settings

In Claude Desktop, open settings:

• macOS: Go to Claude -> Settings… from the menu bar.
• Windows: Access settings through the application menu.

Step 2: Open the MCP configuration

Select Developer from the left sidebar, then click Edit Config. This will create or open the MCP configuration file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Step 3: Add the MCP server configuration

Replace the file content with your Gram MCP configuration. For a public server, use:

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

For an authenticated server, use:

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

Step 4: Test the connection

Save the configuration file, then close Claude Desktop completely and reopen it. When the application has restarted, click the hamburger icon in the chat field to see the available tools.

Test the connection by asking:

What's the vibe today?

Claude will use your Gram-hosted MCP server to check the vibes by calling the Push Advisor API.

Connecting Claude Desktop to your Gram-hosted MCP server using Claude Connectors

Claude Connectors allow you to connect Claude Desktop to your Gram-hosted MCP server without manually editing the configuration file. This is more user-friendly, but comes with one important limitation: your MCP server must be public. If you need to use an authenticated server, you’ll need to use the MCP configuration file method described above.

Here’s how to set up a connection using Claude Connectors:

Step 1: Access Claude Desktop settings

In Claude Desktop, open settings:

• macOS: Go to Claude -> Settings… from the menu bar.
• Windows: Access settings through the application menu.

Step 2: Open the Connectors tab

Select Connectors from the left sidebar. This is where you can manage your connections to external services.

Step 3: Add a custom connector

Click the Add custom connector button.

In the popup, provide the following information:

• Name: A descriptive name for your connector (e.g., “Push MCP Server”).
• URL: The URL of your Gram-hosted MCP server (e.g., https://app.getgram.ai/mcp/canipushtoprod).

Claude Desktop may show a warning about trusting the server. Since this is your own MCP server, you can safely ignore this warning.

Click Add to create the connector.

Step 4: Test the connection

No need to restart, you can test the connection immediately. In the chat, ask Claude something that requires the MCP server, like:

Can I push to prod today?

Claude should prompt you with a tool call request. This means the connection is working, and Claude can now use your Gram-hosted MCP server to access the Push Advisor API.

Deciding which method to use

Both methods connect Claude Desktop to your Gram-hosted MCP server, but they have different use cases:

• MCP configuration file: Use this method if you need to connect to an authenticated MCP server or if you want more control over the configuration.
• Claude Connectors: Use this method for a simpler setup with public MCP servers. It’s more user-friendly and doesn’t require manual configuration file editing.

Comparison of connection methods

Attribute/Requirement	MCP Configuration File	Claude Desktop Connectors
Public MCP server	✅	✅
Local MCP server	✅	❌
Supports authenticated server	✅	❌
Manual configuration needed	✅	❌
User-friendly setup	❌	✅

Troubleshooting

If you’re experiencing issues:

• Verify the MCP server URL is correct in your configuration
• Check that the API behind the MCP server is reachable from your machine
• Ensure the npx command is available (reinstall Node.js if needed)
• Try restarting Claude Desktop after making configuration changes
• For authenticated servers, verify your Gram API key in the dashboard under Settings > API Keys

What’s next

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