Skip to main content
Glama
GSA-TTS

USA Spending MCP Server

Official
by GSA-TTS
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

USA Spending MCP Server

⚠️ DISCLAIMER: This is a proof of concept and is not intended for production use.

An MCP server for interacting with the USAspending.gov API, with optional login.gov authentication for cloud deployment.

Requirements

  • Python 3.11+

  • uv

Related MCP server: federal-compass-mcp

Installation

Quick Install

uv tool install git+https://github.com/GSA-TTS/usa-spending-mcp-server

Development Setup

git clone https://github.com/GSA-TTS/usa-spending-mcp-server
cd usa-spending-mcp-server
uv sync --dev

Running Modes

The server supports two modes:

Mode

Command

Use Case

stdio

usa-spending-mcp-server

Local use with Claude Desktop

HTTP

usa-spending-mcp-server-http

Cloud deployment with login.gov auth

Local Setup (Claude Desktop)

  1. Get the installed tool path:

    which usa-spending-mcp-server

  2. Add to your Claude MCP config (~/.claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "usa-spending": {
      "command": "/path/to/usa-spending-mcp-server"
    }
  }
}

HTTP Server with Login.gov Authentication

The HTTP server uses login.gov OIDC with PKCE for authentication, suitable for cloud.gov deployment.

Environment Variables

Variable

Required

Description

REQUIRE_AUTH

No

Set to "false" to disable auth (default: "true")

BASE_URL

If auth enabled

Public URL of the server (e.g., https://usa-spending-mcp.app.cloud.gov)

LOGINGOV_CLIENT_ID

If auth enabled

Your login.gov application client ID

JWT_SIGNING_KEY

If auth enabled

Secret key for signing JWTs (generate with python -c "import secrets; print(secrets.token_hex(32))")

LOGINGOV_CONFIG_URL

No

OIDC discovery URL (defaults to login.gov sandbox)

PORT

No

Server port (default: 8080)

Login.gov Setup

  1. Register at partners.login.gov

  2. Create a new OIDC application:

    • Protocol: OpenID Connect with PKCE (public client)

    • Redirect URI: {BASE_URL}/auth/callback

  3. Note your client ID for LOGINGOV_CLIENT_ID

Running Locally

Without authentication (development):

uv run task dev

With authentication:

export BASE_URL=http://localhost:8080
export LOGINGOV_CLIENT_ID=your-client-id
export JWT_SIGNING_KEY=$(python -c "import secrets; print(secrets.token_hex(32))")
uv run task dev-auth

Cloud.gov Deployment

  1. Set environment variables:

    cf set-env usa-spending-mcp-server BASE_URL https://usa-spending-mcp.app.cloud.gov
cf set-env usa-spending-mcp-server LOGINGOV_CLIENT_ID your-client-id
cf set-env usa-spending-mcp-server JWT_SIGNING_KEY your-signing-key

  2. Deploy:

    cf push

Development

Available Tasks

uv run task dev          # Run HTTP server without auth
uv run task dev-auth     # Run HTTP server with auth
uv run task lint         # Check code with ruff
uv run task lint-fix     # Fix linting issues
uv run task format       # Format code with ruff
uv run task test         # Run tests
uv run task test-cov     # Run tests with coverage
uv run task ci           # Run all CI checks

Code Quality

This project uses ruff for linting and formatting.

LLM-Based Evals (Optional)

For local testing of tool behavior using mcp-evals:

cd evals
npm install
ANTHROPIC_API_KEY=your-key npm run eval

See evals/README.md for details.

Project Structure

src/
  usa_spending_mcp_server/
    server.py        # stdio MCP server (Claude Desktop)
    server_http.py   # HTTP server with auth (cloud.gov)
    auth.py          # login.gov OIDC authentication
tests/               # Python unit tests
evals/               # LLM-based evals (optional)
manifest.yml         # cloud.gov deployment config
pyproject.toml

Available Tools

3 tools
executeB

Chain await call_tool(...) calls in one Python block; prefer returning the final answer from a single block. Use return to produce output. Only call_tool(tool_name: str, params: dict) -> Any is available in scope.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesPython async code to execute tool calls via call_tool(name, arguments)

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully disclose behavior. It mentions that only `call_tool` is available and that `return` produces output, but it omits critical details like execution environment, side effects, timeout, error handling, and security restrictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three concise sentences with no extraneous content, front-loaded with the core purpose, and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite low complexity (one parameter), the description is insufficient for safe usage of arbitrary code execution. It lacks details on output handling, variable scope, error propagation, and security constraints, making it incomplete for an agent to reliably invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds minimal value by detailing the `call_tool` signature and return usage, but it essentially repeats the schema's code description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states that the tool executes Python code to chain asynchronous tool calls via the `call_tool` function, distinguishing it from siblings like `get_schema` and `search` which are for single operations or queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to 'prefer returning the final answer from a single block' implying a pattern, but it does not explicitly state when to use this tool versus making individual calls or using alternatives, nor does it provide exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_schemaA

Get parameter schemas for specific tools.

Use after searching to get the detail needed to call a tool.

ParametersJSON Schema
NameRequiredDescriptionDefault
toolsYesList of tool names to get schemas for
detailNo'brief' for names and descriptions, 'detailed' for parameter schemas as markdown, 'full' for complete JSON schemasdetailed

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and the description does not disclose any behavioral traits such as side effects, authorization needs, or rate limits. For a read-only tool, the description could mention that it is non-destructive, but it remains silent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. Essential information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool is simple, output schema exists, so description doesn't need to explain return values. The description covers the essential usage flow, but slight improvement could mention that it returns JSON schemas.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds context about using after searching, which helps understand the purpose of the 'tools' parameter, but doesn't add extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool gets parameter schemas for specific tools. Verb 'get' and resource 'parameter schemas for specific tools' are specific and distinct from sibling tools like execute, search, and tags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use after searching to get the detail needed to call a tool.' This gives clear context for when to use it, though it doesn't mention when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedexecute
    • First observedget_schema
    • First observedsearch
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation5/5

The three tools (execute, get_schema, search) have clearly distinct purposes: search finds tools, get_schema retrieves parameter details, and execute runs tools. No overlap.

Naming Consistency4/5

All tools use lowercase verbs, which is consistent. However, the pattern varies: 'execute' is a standalone verb, while 'get_schema' and 'search' combine verb and noun. Minor deviation from a strict pattern.

Tool Count1/5

With only 3 generic meta-tools and no domain-specific tools for USA Spending, the tool count is extremely insufficient for the server's purported purpose. It should have at least basic query tools for spending data.

Completeness1/5

The server claims to be about USA Spending but provides no tools to access spending data. The entire domain surface is missing, making it severely incomplete.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • actual-mcp

    s-stefanov
    A
    license
    B
    quality
    B
    maintenance
    MCP server for integrating Actual Budget with Claude and other LLM assistants.
    17
    610 npm
    234
    TypeScript
    MIT

  • federal-compass-mcp

    skivuha
    A
    license
    A
    quality
    B
    maintenance
    An MCP server that connects Claude to the USAJobs API, enabling natural language search for federal jobs, translation of government jargon, CV qualification analysis, and explanation of federal concepts like GS grades and clearances.
    10
    68 npm
    12
    MIT

  • USAspending MCP Server

    haydentbs
    A
    license
    A
    quality
    D
    maintenance
    Read-only MCP server for exploring US federal spending data via the USAspending.gov API, enabling natural language queries on awards, agencies, recipients, and spending trends.
    12
    MIT

  • USAspending MCP

    jsconiers
    A
    license
    Not graded
    quality
    D
    maintenance
    A free, key-less MCP server for querying U.S. federal spending data from USAspending.gov, including contracts, grants, loans, recipients, agencies, and geographic breakdowns.
    MIT