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.

New tools must ship with an eval file under evals/<tool>.eval.ts (or evals/<resource>/<tool>.eval.ts). Evals drive natural-language prompts against the registered tool to verify the description + zod schema are good enough for a model to find and call it. Most existing tools predate evals — do not backfill unless asked. See .agents/skills/writing-evals/SKILL.md for the full eval guide (tool authoring: .agents/skills/writing-mcp-tools/SKILL.md).

Results are persisted to evals/evalite.db (a SQLite file committed to the repo as a shared baseline). Evals are not run in CI — they are a local/PR discipline. The workflow when adding or changing a tool:

1. Write or update evals/<...>/<your-tool>.eval.ts.
2. Run only that file — npm run eval -- ./evals/<...>/<your-tool>.eval.ts. Other tools' evals are not re-executed, so their existing rows in the db stay untouched.
3. Commit the updated evals/evalite.db alongside the tool change. The created_at columns serve as an audit trail for when each eval last ran versus when its underlying tool last changed.

npm run eval with no path runs every eval file and appends rows for all of them — useful when intentionally refreshing the whole baseline, not for everyday development.

The live UI for the committed evalite.db is published to GitHub Pages at https://vantage-sh.github.io/vantage-mcp-server/. The site rebuilds automatically on every push to main that touches evals/evalite.db (see .github/workflows/deploy-eval-results.yml).

To browse results locally without publishing:

npm run eval:export
open ./evalite-export/index.html

This produces a static bundle from the current state of evals/evalite.db and does not re-execute any evals. The evalite-export/ directory is gitignored.

• 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
• npm run eval - Run all evals (use npm run eval -- ./evals/<path> to filter to one file)
• npm run eval:dev - Run evalite in watch mode with UI on localhost:3006
• npm run eval:export - Build a static HTML bundle of the current evalite.db under ./evalite-export/ (no re-execution)

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.