# How to connect Claude Code to MCP

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's terminal-based tool that brings Claude's capabilities directly to your command line. Unlike Claude Desktop, which runs in a graphical interface, the Claude Code CLI can access your current project folder.

![Claude Code terminal interface showing welcome message](/assets/docs/gram/img/guides/claude-code/claude-code-intro.png)

When combined with [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers, Claude Code becomes even more useful. 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 shows you how to connect Claude Code to a [Gram-hosted MCP server](https://www.speakeasy.com/blog/release-gram-beta) using Taskmaster, a full-stack CRUD application for task and project management. Taskmaster includes a web UI for managing projects and tasks, a built-in HTTP API, OAuth 2.0 authentication, and a Neon PostgreSQL database for storing data. Try the [demo app](https://taskmaster-speakeasyapi.vercel.app/) to see it in action.

You'll learn how to set up the connection, test it, and use natural language to manage tasks, projects, and workflows through Claude Code.

Find the full code and OpenAPI document in the [Taskmaster repository](https://github.com/speakeasy-api/taskmaster).

## Prerequisites

To follow this tutorial, you need:

- A [Gram account](https://app.getgram.ai)
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed

## Getting started

First, [authenticate with Claude Code](https://docs.anthropic.com/en/docs/claude-code/setup).

Then, verify that Claude Code is installed correctly:

```bash
claude --help
```

If installation is successful, you'll see Claude Code's available commands and options.

## Creating an MCP server

Before connecting Claude Code to a Taskmaster MCP server, you first need to create one. Follow our guide to [creating a Taskmaster MCP server](/docs/mcp/build/examples/creating-taskmaster-mcp-server).

## Connecting Claude Code to your Gram-hosted MCP server

Once your Taskmaster MCP server is ready, there are three ways to connect it to Claude Code:

- Use the `claude mcp add` command from the Gram installation page (recommended).
- Use the Gram CLI to automatically configure the connection.
- Manually add the MCP server configuration.

### Quick Setup from the Gram installation page

The quickest way to connect Claude Code to a Gram-hosted MCP server is to copy the installation command from the Gram dashboard.

Go to your toolset's installation page at `https://app.getgram.ai/mcp/<your-toolset-slug>/install` and select **Claude Code**. Copy the installation command and run it in your terminal:

![Screenshot showing the Gram installation page with client options](/assets/docs/gram/img/guides/install-clients-page.png)

```bash
claude mcp add --transport http "taskmaster" "https://app.getgram.ai/mcp/your-toolset-slug"
```

Replace `your-toolset-slug` with the slug of your toolset.

### Using the Gram CLI

Alternatively, you can use the Gram CLI to configure the connection. The CLI automatically fetches your toolset configuration and creates the appropriate settings file.

Go to your toolset's installation page and select **Gram CLI** to copy the installation command, or run:

```bash
gram install claude-code --toolset taskmaster
```

![Screenshot showing the output of the gram install claude-code command](/assets/docs/gram/img/guides/claude-code/gram-install-claude-code-command.png)

This command automatically:
- Fetches your toolset configuration from Gram
- Derives the MCP URL and authentication settings
- Creates the correct configuration (by default in user-level `~/.claude.json`)

#### Setting up environment variables

If your toolset requires authentication, you'll need to set up environment variables. The `gram install` command will display the required variable names and provide the export command you need to run to set the variable value.

For the Taskmaster toolset, you'll need to set the `MCP_TASK_MASTER_API_KEY` environment variable to your Taskmaster API key. You can do this by running the following command:

```bash
export MCP_TASK_MASTER_API_KEY='your-api-key-value'
```

#### Configuration Scopes

You can control where the MCP server configuration is installed using the `--scope` flag:

```bash
# Install to user-level config (default) - available across all projects
gram install claude-code --toolset taskmaster --scope user

# Install to project-level config - can be shared with your team
gram install claude-code --toolset taskmaster --scope project
```

Use `--scope project` when you want to commit the `.mcp.json` configuration to version control and share it with your team.

For more details and advanced options, see the [`gram install` documentation](/docs/mcp/reference/command-line/install).

### Manual Setup

Alternatively, you can manually add an MCP server in Claude Code using the `claude mcp add` command:

- If you're using the **Pass-through Authentication** configuration, the JSON configuration looks like this:

    ```json
    {
      "mcpServers": {
        "taskmaster": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://app.getgram.ai/mcp/your-taskmaster-slug",
            "--header",
            "MCP-TASKMASTER-API-KEY:<your-api-key>"
          ]
        }
      }
    }
    ```

    So you can add the server by running the following (replace `<your-api-key>` with the actual values from your Taskmaster MCP server configuration and `your-taskmaster-slug` with your MCP server slug):

    ```bash
    claude mcp add taskmaster --scope project -- npx mcp-remote https://app.getgram.ai/mcp/your-taskmaster-slug --header "MCP-TASKMASTER-API-KEY:<your-api-key>"
    ```

- Whereas if you're using the **Managed Authentication** configuration, the JSON configuration looks like this:

    ```json
    {
      "mcpServers": {
        "taskmaster": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "https://app.getgram.ai/mcp/your-taskmaster-slug",
            "--header",
            "Authorization:Bearer <your-gram-api-key>"
          ]
        }
      }
    }
    ```

    So you can add the server by running the following (replace `<your-gram-api-key>` with your actual Gram API key and `your-taskmaster-slug` with your MCP server slug):

    ```bash
    claude mcp add taskmaster --scope project -- npx mcp-remote https://app.getgram.ai/mcp/your-taskmaster-slug --header "Authorization: Bearer <your-gram-api-key>"
   ```

Both configurations use the same commands:

- `taskmaster` is the name you've given the server locally.
- `--scope project` adds the server to a local `.mcp.json` file that can be shared with other users on the project. Read more about other [scope options](https://docs.anthropic.com/en/docs/claude-code/mcp#mcp-installation-scopes) in the Anthropic docs.
- `--` separates Claude Code flags from the server command.
- `npx mcp-remote` is the package that handles remote MCP server connections.
- `--header` is the flag that passes headers to the remote server.

## Verifying the connection

Check that the server was added successfully:

```bash
claude mcp list
```

You should see `taskmaster` in the list.

To see the full configuration, run this command:

```bash
claude mcp get taskmaster
```

![Screenshot showing the terminal output after successfully adding and configuring an MCP server in Claude Code](/assets/docs/gram/img/guides/claude-code/claude-code-mcp-install.png)

## Testing the setup

Now test the connection by starting Claude Code and managing some tasks.

First, start an interactive session with Claude Code in your terminal:

```bash
claude
```

Ask Claude a basic question like, *"Can you help me create a new task?"*

<video width="600" muted={true} controls>
  <source src="/assets/docs/gram/videos/claude-code-showcase.mp4" type="video/mp4" />
    Your browser does not support the video tag.
</video>

## Troubleshooting

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

### Server not found

If Claude Code can't find your server:

- Check whether the server is listed.

    ```bash
    claude mcp list
    ```

- Remove and re-add the server

    ```bash
    claude mcp remove taskmaster
    claude mcp add taskmaster --scope project -- npx mcp-remote https://app.getgram.ai/mcp/your-taskmaster-slug --header "Authorization:Bearer <your-gram-api-key>"
    ```

### 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 Taskmaster API base URL is accessible.

### Tool calls not working

If Claude Code isn't calling the tools:

- Test the MCP server in the **Gram Playground** first.
- Check that the toolset includes the tools to use.
- Verify the environment is correctly configured with the required variables.

## What's next

You now have Claude Code connected to a Gram-hosted MCP server with task management capabilities.

Ready to build your own MCP server? [Try Gram today](/book-demo) and see how easy it is to turn any API into agent-ready tools.