# Using Vellum agents with Gram-hosted MCP servers

[Vellum](https://www.vellum.ai/) agents can connect to Model Context Protocol (MCP) servers to interact with external APIs and tools. This guide shows you how to connect a Vellum agent to a [Gram-hosted MCP server](https://www.speakeasy.com/blog/release-gram-beta) using the Push Advisor API from the Gram [core concepts](https://www.speakeasy.com/mcp/core-concepts) guide.

By the end, you'll have a Vellum Workflow that uses natural language to check whether it's safe to push to production.

Find the full code and OpenAPI document in the [Push Advisor API repository](https://github.com/ritza-co/gram-examples/tree/main/push-advisor-api).

## Prerequisites

To follow this tutorial, you need:

- A [Gram account](https://app.getgram.ai)
- A [Vellum account](https://vellum.ai/)

## Creating a Gram MCP server

If you already have a Gram MCP server configured, you can skip to [connecting Vellum to your Gram-hosted MCP server](#connecting-vellum-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 [core concepts](https://www.speakeasy.com/mcp/core-concepts) documentation.

### Setting up a Gram project

In the [Gram dashboard](https://app.getgram.ai), click **New Project** to create a new project. Enter a project name and click **Submit**

![Screenshot of the Gram dashboard showing the New Project modal](/assets/docs/gram/img/api-clients/vellum/gram-new-project.png)

Once you've created the project, click the **Get Started** button.

Choose **Start from API**. Gram then guides you through the following steps.

#### Step 1: Upload the OpenAPI document

Upload the [Push Advisor OpenAPI document](https://github.com/ritza-co/gram-examples/blob/main/push-advisor-api/openapi.yaml), enter the name of your API, and click **Continue**.

![Screenshot of the upload your OpenAPI document dialog](/assets/docs/gram/img/api-clients/vellum/upload-openapi-spec.png)

#### Step 2: Create a toolset

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

![Screenshot of the create toolset dialog](/assets/docs/gram/img/api-clients/vellum/create-toolset.png)

Notice that the **Name Your Toolset** dialog displays the names of the tools that Gram will generate from your OpenAPI document.

#### Step 3: Configure MCP

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

![Screenshot of the configure MCP dialog](/assets/docs/gram/img/api-clients/vellum/configure-mcp.png)

Gram will create a new toolset from the OpenAPI document.

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

![Screenshot of the Gram dashboard showing the Push Advisor toolset](/assets/docs/gram/img/api-clients/vellum/toolset-created.png)

### Configuring environment variables

[Environments](/docs/mcp/secure/environments) store API keys and configuration separately from your toolset logic.

In the **Environments** tab, click the **Default** environment. Then click **Fill for Toolset**, select the **Push Advisor** toolset, and click **Fill Variables** to automatically populate the required variables.

![Screenshot showing the fill for toolset dialog to automatically populate required variables](/assets/docs/gram/img/api-clients/vellum/fill-env-vars-toolset.png)

The Push Advisor API is hosted at `https://canpushtoprod.abdulbaaridavids04.workers.dev`, so set the `<your_API_name>_SERVER_URL` environment variable to `https://canpushtoprod.abdulbaaridavids04.workers.dev`. Click **Save**.

![Set server URL](/assets/docs/gram/img/api-clients/vellum/set-server-url.png)

### 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 the title of the server.

On the **MCP Details** page, click **Enable** and then **Enable Server** to enable the server.

![Screenshot of the MCP details page](/assets/docs/gram/img/api-clients/vellum/mcp-details.png)

Take note of your MCP server URL in the **Hosted URL** section.

[Generate a GRAM API key](/docs/mcp/secure/api-keys) in the **Settings** tab.

## Connecting Vellum to your Gram MCP server

With the Push Advisor MCP server ready, you can connect it to Vellum by configuring a tool in an agent node.

## Adding a secret environment to Vellum

Configuring the MCP server requires your Gram Key. To add it as a secret, navigate to **Profile → Settings → Secrets & Variables → + Add Environment Variable**.

![Screenshot of Vellum profile settings page](/assets/docs/gram/img/api-clients/vellum/vellum-profile-settings.png)

Enter `GRAM_KEY` for the variable name, paste your Gram key as the value, and click **Create Variable**.

![Screenshot of creating the GRAM_KEY environment variable in Vellum](/assets/docs/gram/img/api-clients/vellum/vellum-create-gram-key-variable.png)

## Adding a Vellum agent

If you see a prompt input screen on the **New Workflow** creation screen, send Vellum the following prompt:

```
Create entrypoint, agent, and output nodes
```

Otherwise, use the **Create Workflow** button to create a new Workflow:

- Add an **Agent** node.

  ![Screenshot of adding an agent node to a Vellum Workflow](/assets/docs/gram/img/api-clients/vellum/vellum-add-agent-node.png)

- Click the **Agent** node, then click **+ Tool**.

  ![Screenshot of the Add Tool button in the agent node](/assets/docs/gram/img/api-clients/vellum/vellum-add-tool-button.png)

- Select **MCP Server** from the **Tool Type** options.

  ![Screenshot of selecting MCP Server from the tool options](/assets/docs/gram/img/api-clients/vellum/vellum-select-mcp-server.png)

- Configure the MCP server as follows:

  - **Server Name:** Push Advisor
  - **Server URL:** `https://app.getgram.ai/mcp/your-server-slug` (your Gram MCP server URL)
  - **Authentication:** API Key
  - **API Key Header Name:** Authorization
  - **API Key Value:** GRAM_KEY

  ![Screenshot of the MCP server configuration modal in Vellum](/assets/docs/gram/img/api-clients/vellum/vellum-configure-mcp-server.png)

- Click **Confirm** to save.

  Vellum automatically discovers the available tools. You should see the MCP server listed under **Tools**.

- Now, go to the **Overview** tab and click **Edit Prompt** to add a prompt.

![Screenshot of the Edit Prompt button in the agent overview](/assets/docs/gram/img/api-clients/vellum/vellum-edit-prompt-button.png)

- In the modal, enter this system prompt:

  ```
  Is it safe to push to production today?
  ```

  ![Screenshot of adding a system prompt to the agent](/assets/docs/gram/img/api-clients/vellum/vellum-add-system-prompt.png)

- Connect the **Entrypoint** node to the **Agent** node, then connect the **Agent** node to the **Output**. Click on the **Output** node and under **Overview → Output Value**, select **Agent** for the **Node Output**, and select **Text** for the **Output Name**.

  ![Screenshot of connecting Workflow nodes in Vellum](/assets/docs/gram/img/api-clients/vellum/vellum-connect-workflow-nodes.png)

- Click **▶️ Run**. The Workflow should return a response indicating whether pushing to production is safe based on the Push Advisor server's evaluation.

  ![Screenshot of the Workflow response showing the agent output](/assets/docs/gram/img/api-clients/vellum/vellum-workflow-response.png)

## Troubleshooting

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

### MCP Client not connecting

If the MCP client can't connect to your server:

- Verify the server URL is correct.
- Check that the MCP server is published as public in Gram.
- For authenticated servers, ensure your Gram API key is valid.
- Test the connection using the Gram Playground first.

### Tool calls not working

If the AI agent isn't calling the MCP tools:

- Ensure the MCP client is properly configured in the AI Agent node.
- Check that your AI model has sufficient context about available tools.
- Try being more explicit in your prompts about using the Push Advisor tool.

### Authentication errors

For authenticated servers:

- Verify your Gram API key in the dashboard under **Settings → API Keys**.
- Ensure the authorization header format is correct.
- Check that environment variables are correctly set in Gram.

## What's next

You now have Vellum connected to a Gram-hosted MCP server, enabling AI-powered automation workflows with access to your APIs and tools.

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.