Budget MCP Server

A local MCP (Model Context Protocol) server that provides PwC Coding Agents budget status information directly within Claude Code conversations.

Overview

The Budget MCP Server allows you to query your PwC Coding Agents budget status without leaving Claude Code. Simply ask Claude about your budget, and it will automatically fetch and display your current usage, limits, and remaining budget.

What It Does

• Provides real-time budget information through Claude Code
• Caches responses (60s TTL) to minimize API calls
• Exposes budget data as both a tool and a resource
• No manual authentication needed (uses your Claude Code settings)

Prerequisites

Before installing, ensure you have:

• Node.js >= 18.0.0

  node --version

• Claude Code configured with PwC AI-CoE Coding Agents Gateway (see Claude Code Configuration)

Installation

Step 1: Download the MCP Server

Download the package from the gateway:

📥 Download budget-mcp.tgz

Or download directly via terminal:

curl -O https://idi-coding-agents.pwc.it/downloads/budget-mcp.tgz

Step 2: Install Globally

Install the package using npm:

npm install -g ./budget-mcp.tgz

This makes the pwc-budget-mcp command available globally.

Step 3: Configure Claude Code

Find your installation path:

After installing, run this command to discover where pwc-budget-mcp was installed:

which pwc-budget-mcp

Copy the output path (e.g., /usr/local/bin/pwc-budget-mcp).

Option A: Use the CLI (Recommended)

claude mcp add --transport stdio pwc-budget -- /path/from/which/command/pwc-budget-mcp

Replace /path/from/which/command/pwc-budget-mcp with the output of which pwc-budget-mcp.

Option B: Manual JSON configuration

Add the MCP server to ~/.claude.json (note: this is not ~/.claude/settings.json — MCP servers are configured in a separate file):

{
  "mcpServers": {
    "pwc-budget": {
      "command": "/path/from/which/command/pwc-budget-mcp"
    }
  }
}

If the file already exists with other MCP servers, add "pwc-budget" to the existing mcpServers object.

Use Absolute Path

You must use the full absolute path from the which command. Claude Code may not have access to your shell's PATH, so using just pwc-budget-mcp without the full path will fail.

MCP config location

MCP servers go in ~/.claude.json, not in ~/.claude/settings.json. The settings.json file is for environment variables, permissions, and other Claude Code settings. See the official MCP docs for details on configuration scopes.

Step 4: Restart Claude Code

After updating your settings, restart Claude Code to load the new MCP server:

# Exit Claude Code (Ctrl+D or type 'exit')
# Then restart
claude

Usage

Once configured, you can query your budget status in several ways:

Ask Claude Directly

Simply ask Claude about your budget:

• "What's my PwC Coding Agents budget status?"
• "How much budget do I have left?"
• "Check my PwC budget"

Claude will automatically use the MCP server to fetch and display your current budget information.

Example Response

**PwC Coding Agents Budget**: 🟢 26%

**Usage**: €286.00
**Limit**: €1100.00
**Remaining**: €814.00

**Status**:
- ✅ Budget usage is healthy

Budget Indicators

The response includes color-coded emoji indicators:

Emoji	Meaning	Usage Level
🟢	Healthy	Less than 70% used
🟡	Warning	70-90% used
🔴	Critical	More than 90% used

How It Works

The MCP server:

1. Reads ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN from ~/.claude/settings.json
2. Queries the /quota/status endpoint at the gateway
3. Caches the response for 60 seconds to minimize API calls
4. Exposes budget data through the MCP protocol

Claude Code can then access this information through:

• Tool: get_budget_status - callable tool that returns budget info
• Resource: budget://status - resource that can be read anytime

Cache Behavior

To avoid excessive API calls:

• Cache TTL: 60 seconds
• Cache location: In-memory (cleared on server restart)
• Cache refresh: Automatic when TTL expires

This means if you ask for your budget multiple times within 60 seconds, the MCP server will return cached data without hitting the API.

Troubleshooting

MCP Server Not Found

If Claude Code can't find the MCP server:

1. Verify the installation:

   which pwc-budget-mcp

2. Check if the command is executable:

   pwc-budget-mcp --help 2>&1 | head -5

3. Ensure Node.js >= 18 is installed:

   node --version

Budget Data Not Showing

If the MCP server can't fetch budget data:

1. Verify your Claude Code settings contain the required environment variables:

   cat ~/.claude/settings.json | grep -A2 '"env"'

2. Test connectivity to the gateway:

   curl -s https://idi-coding-agents.pwc.it/quota/status -H "Authorization: Bearer apikey=<your-key>&tenantid=<your-id>"

3. Ensure you're connected to PwC VPN (Italy or Italy On-Premise)

"Unknown tool" Error

If Claude reports an unknown tool:

1. Check that the MCP server is properly configured in ~/.claude.json
2. Restart Claude Code to reload the MCP configuration
3. Verify the MCP server is running:

   ps aux | grep pwc-budget-mcp

Installation Issues

If npm install fails:

• Permission denied: Use sudo (not recommended) or configure npm to use a user-local directory:

  npm config set prefix ~/.npm-global
  export PATH=~/.npm-global/bin:$PATH

• Node version too old: Upgrade Node.js to >= 18:

  # macOS
  brew upgrade node

Updating the MCP Server

When a new version is released:

1. Download the latest version:

   curl -O https://idi-coding-agents.pwc.it/downloads/budget-mcp.tgz

2. Reinstall globally:

   npm install -g ./budget-mcp.tgz

3. Restart Claude Code

Note: The /downloads/budget-mcp.tgz URL always points to the latest version.

Comparison: MCP Server vs Status Line

Both tools provide budget information, but serve different purposes:

Feature	MCP Server	Status Line Script
Access	In conversation, ask Claude	Always visible in terminal
Usage	Query when needed	Continuous display
Setup	npm package	Bash script
Dependencies	Node.js	jq, bash
Cache	60s (in-memory)	60s (file-based)
Best for	On-demand budget checks	Constant budget awareness

Recommendation: Use both! The status line gives you constant visibility, while the MCP server lets you query details from within your conversation with Claude.

---

Related Tools

• Status Line Script - Display budget in terminal status bar
• Telemetry Setup - Configure usage tracking for ROI analysis