Vantage MCP Server

Use natural language to explore your organization's cloud costs via MCP clients, like Claude, Cursor, and others. Ask questions about your organization's previous and current cloud cost spend, cost tagging, provider integrations, and more.

This repository supports two different deployment modes for the Vantage MCP Server:

• Self-Hosted (Local) Mode: via src/local.ts

  • Runs locally using Standard Input/Output (stdio) Transport
  • Direct communication with MCP clients
  • Requires a Vantage API token
  • Best for individual users, development, or when you want full control

• Remote (HTTP) Mode: via src/cf-worker.ts

  • Runs as a Cloudflare Worker with HTTP endpoints
  • Supports multiple authentication methods (OAuth, API tokens, Vantage headers)
  • Accessible via web requests
  • Best for teams, production deployments, or when you need web-based access

  📝 Note: For using the remote HTTP version in a non-development workflow, see the Vantage MCP documentation.

The Vantage MCP Server exposes a set of tools for listing, querying, and creating Vantage resources. These tools can be invoked by any compatible MCP client and are available in /src/tools.

• Node.js (v18 or higher) and npm installed
• Access to an MCP-compatible client (such as Claude Desktop, Cursor, or Goose)
• A Vantage account with at least one connected provider (AWS, Azure, Google Cloud, etc.)

1. Clone this repo and install dependencies:

   git clone https://github.com/vantage-sh/vantage-mcp-server
   cd vantage-mcp-server
   npm install

2. Create a Vantage API token following the Vantage documentation.

📝 Note: This self-hosted mode is intended for developing and contributing to the MCP server. For personal use, the recommended approach is to use npx -y vantage-mcp-server.

To use the self-hosted MCP server, you'll need to configure your MCP client to launch the server. The configuration process varies depending on which MCP client you use. Example clients include:

• Claude for Desktop
• Cursor
• Goose

See the MCP documentation for a list of available clients. Detailed instructions for Claude for Desktop, Cursor, and Goose are provided below.

1. Download Claude for Desktop.
2. From the top of Claude for Desktop, click Claude > Settings (keyboard shortcut Command + ,).
3. In the left menu of the Settings pane, select Developer.
4. Click Edit Config. A configuration file is created at:

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

5. Open the claude_desktop_config.json file and update its contents. Replace the placeholders <path_to_repository> with the path where you cloned this repository, and <personal_vantage_api_token> with your Vantage API token.

   {
     "mcpServers": {
       "Vantage": {
         "command": "npx",
         "args": ["tsx", "<path_to_repository>/src/local.ts"],
         "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
       }
     }
   }

   📝 Note: The server uses tsx to run TypeScript directly. If you have tsx installed globally, you can use "command": "tsx" and "args": ["<path_to_repository>/src/local.ts"] instead.

6. Save the configuration file and restart Claude.

7. In the left corner of the Claude for Desktop input box, click the Search and tools icon to see the available tools for the Vantage MCP Server.

8. Once you've set up the configuration, you can start prompting Claude. Each time you use a new tool, Claude will ask for your approval before proceeding.

1. Download Cursor.

2. Open Cursor and click Cursor > Settings > Cursor Settings from the menu bar.

3. In the left pane, select Tools & MCP.

4. Click New MCP Server.

5. Update the contents of the opened mcp.json file. Make sure to replace the placeholders <path_to_repository> with the path where you cloned this repository, and <personal_vantage_api_token> with your Vantage API token.

   {
     "mcpServers": {
       "Vantage": {
         "command": "npx",
         "args": ["tsx", "<path_to_repository>/src/local.ts"],
         "env": { "VANTAGE_TOKEN": "<personal_vantage_api_token>" }
       }
     }
   }

   📝 Note: The server uses tsx to run TypeScript directly. If you have tsx installed globally, you can use "command": "tsx" and "args": ["<path_to_repository>/src/local.ts"] instead.

6. Save the configuration file.

7. You will see the Vantage MCP Server with tools enabled in the Installed MCP Servers list.

1. Download Goose.
2. Open Goose. In the left navigation, select Extensions.
3. Click Add custom extension.
4. In the Extension Name field, enter Vantage.
5. For Type, select STDIO.
6. In the Description field, enter Query costs and usage data.
7. In the Command field, enter npx tsx <path_to_repository>/src/local.ts (replace <path_to_repository> with the actual path to your cloned repository).
8. In the Environment Variables section, add a new variable with the name VANTAGE_TOKEN and the value set to your Vantage API token. Next to the environment variable, click Add.
9. Click Add Extension.

To develop and test the HTTP/Cloudflare Worker mode locally, you can use npm run dev. This starts a local development server using Wrangler.

For easier local development, you can configure the VANTAGE_MCP_TOKEN environment variable in wrangler-DEV.jsonc to bypass OAuth authentication. When set, the server will use this token directly instead of requiring OAuth flow.

1. Open wrangler-DEV.jsonc and set the VANTAGE_MCP_TOKEN value in the vars section:

   {
     "vars": {
       "VANTAGE_MCP_TOKEN": "your_vantage_api_token_here",
       // ... other vars
     }
   }

2. Run the development server:

   npm run dev

3. The server will be available at http://localhost:8787 (Wrangler's default port, as configured in wrangler-DEV.jsonc) and will bypass OAuth, using the VANTAGE_MCP_TOKEN for authentication instead.

📝 Note: Setting VANTAGE_MCP_TOKEN enables direct token mode, which bypasses OAuth entirely. This is useful for local development or for MCP clients without OAuth support or the ability to pass headers.

To add a new tool to the application, create a file at src/tools/<tool-name>.ts, and use the following structure:

import registerTool from "./structure/registerTool";
import MCPUserError from "./structure/MCPUserError";
import z from "zod";

const description = `
Your description here.
`.trim();

const args = {
    exampleArg: z.string(),
};

export default registerTool({
    name: "my-tool-name", // replace with the tool name
    description,
    async execute(args, ctx) {
        // args will be a resolved version of the schema
        console.log(args);

        if (args.exampleArg === "something") {
            // We throw a MCPUserError to send a message to the user
            // The argument is the body
            throw new MCPUserError({ my: "error" });
        }

        // ctx is a ToolCallContext, this has the function to call the vantage api

        // Then we just return
        return { a: "b" };
    },
});

Important: When you add or remove a tool, run npm run generate-tools-index to update the tools index.

• npm run dev - Start development server with Wrangler DEV config
• npm run local - Run local stdio MCP server (uses tsx for TypeScript support)
• npm run --silent local - Run local MCP server with reduced output (recommended for development)
• npm run inspect - Launch MCP inspector tool
• npm run format - Format code using Biome
• npm run lint:fix - Lint and auto-fix issues with Biome
• npm run type-check - Run TypeScript type checking
• npm run cf-typegen - Generate Cloudflare Worker types
• npm run generate-tools-index - Generate tools index after adding/removing tools

The /public folder is publicly accessible. Any file like /public/asset.gif is accessible as /asset.gif when running locally or on Cloudflare.

If you'd like to contribute to this project:

1. Fork this repository.
2. Create a new branch: git checkout -b feature/my-feature.
3. Make your changes.
4. Ensure your code is formatted and builds cleanly:

   npm run format
   npm run lint:fix
   npm run type-check

5. Submit a pull request.

We welcome community contributions, improvements, and bug fixes.

See the LICENSE.md file for commercial and non-commercial licensing details.