Capture MCP Server

An MIT-licensed, AI-native Model Context Protocol (MCP) server that integrates SAM.gov, USASpending.gov, Tango, and HigherGov APIs to capture and analyze federal procurement and spending data through natural language queries. Responses include both human-readable text and structured JSON so MCP-compatible clients can consume the data programmatically.

Overview

Capture MCP empowers users to capture and query federal entity, opportunity, and spending data through LLM applications like Claude Desktop. It provides 34 specialized tools that can search, analyze, aggregate, and join data from multiple government APIs.

Compatible with: Claude Desktop, ChatGPT Desktop (Pro+), and any MCP-compatible client

Related MCP server: USASpending MCP Server

Table of Contents

• Features

• Tool Availability Matrix

• Quick Start

• Installation Methods

  • Method 1: One-Click Installation (Claude Desktop)

  • Method 2: Standard MCP Configuration

  • Method 3: Hosted Version (AWS Serverless)

• API Keys

• Testing & Verification

• Troubleshooting

• Example Queries

• API Documentation

• Development

• Contributing

• License

• Support

Features

• Structured outputs – Every tool call returns JSON alongside descriptive text for best-in-class client compatibility.

• Safe rate limiting – Queue-based throttling prevents accidental quota overruns on SAM.gov, USASpending.gov, and Tango APIs.

• Input hygiene – Argument sanitization strips control characters while keeping meaningful punctuation intact.

Reference Data (1 tool - No API key required)

• lookup_reference_code - Official FPDS descriptions for set-aside, extent-competed, award-type, solicitation-procedure, and competition codes (e.g. 8A = 8(a) Competed vs 8AN = 8(a) Sole Source)

USASpending.gov Integration (6 tools - No API key required)

• get_usaspending_awards - Agency award summaries

• get_usaspending_spending_by_category - Spending breakdowns

• get_usaspending_budgetary_resources - Budget information

• search_usaspending_awards_by_recipient - Find awards by company

• get_award_detail - Full FPDS record for one award (set-aside, extent competed, offers received) — the verification primitive

• aggregate_contracts - Group awards by agency, sub-agency, recipient, NAICS, PSC, month, or set-aside with count/obligations metrics

SAM.gov Integration (4 tools - Requires SAM.gov API key)

• search_sam_entities - Find federal contractors and businesses

• get_sam_opportunities - Discover contract opportunities

• get_sam_entity_details - Get comprehensive company profiles

• check_sam_exclusions - Verify contractor eligibility

Data Joining (2 tools - Requires SAM.gov API key)

• get_entity_and_awards - Combine SAM entity data with spending history

• get_opportunity_spending_context - Link opportunities with market context

Tango API Integration (12 tools - Requires Tango API key)

• search_tango_contracts - Search federal contracts through unified API

• search_tango_grants - Search federal grants and financial assistance

• get_tango_vendor_profile - Get comprehensive vendor profiles with history

• search_tango_opportunities - Search contract opportunities with forecasts

• get_tango_spending_summary - Get spending summaries and analytics (page-scoped; use aggregate_contracts for population figures)

• search_tango_protests - Search GAO bid protests (agency, protester, outcome, dates)

• get_tango_protest - Get full bid protest record by ID or case number

• search_tango_idvs - Search IDIQs / BPAs / FSS that issue task orders

• get_tango_idv_children - Get child IDVs, task orders, and transactions under one IDV

• search_tango_vehicles - Search the federal contract-vehicle catalog (GWACs, MAS, BPAs)

• search_tango_otas - Search Other Transaction Authority (OTA) awards

• get_tango_entity_metrics - Time-series obligations for one UEI (month/quarter/year)

HigherGov Integration (9 tools - Requires HigherGov API key)

• search_highergov_forecasts - Forecasts from a HigherGov saved search

• search_highergov_opportunities - Active opportunities by set-aside bundle, NAICS, PSC, agency, and dates

• get_highergov_opportunity - One opportunity by ID, SAM notice ID, or URL

• get_opportunity_documents - Solicitation documents and amendments with fetchable URLs

• list_highergov_saved_searches - Saved searches available to the API key

• search_highergov_contracts - Awarded contracts for recompete targeting (agency, NAICS, PSC, set-aside, PoP end, value)

• get_highergov_contract - Full record for one contract by ID or PIID

• search_highergov_people - Federal POCs by agency and role keywords

• get_highergov_person - Full POC profile including verified email

Response conventions

Every list tool follows the same contract, so an agent can always tell what actually ran:

• Filter echo — filters.upstream vs filters.client_side: exactly which filters the upstream API applied and which the server enforced on the returned page.

• Honest totals — total is only populated when trustworthy. Client-side filtering moves it to total_upstream_unfiltered; known-loose upstream matching moves it to total_upstream_unverified. Both come with warnings.

• Labeled units and dates — count_unit says what is being counted (awards vs transactions vs notices) and date_field says which date a date filter compared.

• One cursor shape — next_cursor on every list response; pass it back as cursor to page. null means last page.

• Codes with descriptions — set-aside codes are returned as {code, description}, validated against the FPDS table.

• Unknown parameters are rejected with a bad_request naming the accepted list — never accepted-and-ignored.

Tool Availability Matrix

The server automatically enables tools based on which API keys you provide:

Quick Start

Prerequisites

• Node.js 18+ (included with Claude Desktop for .mcpb installation)

• Claude Desktop or ChatGPT Desktop (Pro/Plus/Business/Enterprise/Education)

• API Keys (Optional - see API Keys section):

  • None required: 7 tools (reference + USASpending.gov) work immediately

  • SAM.gov API key: adds 6 more tools

  • Tango API key: adds 12 more tools

  • HigherGov API key: adds 9 more tools

  • All three keys: all 34 tools

Choose Your Installation Method

For Claude Desktop users: Use Method 1: One-Click Installation for the easiest setup with a graphical API key configuration interface.

For ChatGPT Desktop or other MCP clients: Use Method 2: Standard MCP Configuration which works universally across all MCP-compatible applications.

For hosting your own service: Use Method 3: Hosted Version (AWS Serverless) to deploy a shared Capture MCP service for your organization on AWS.

Installation Methods

Method 1: One-Click Installation (Claude Desktop)

Desktop Extensions (.mcpb files) provide the easiest installation experience for Claude Desktop users. No terminal, no configuration files, no dependency conflicts.

What is a Desktop Extension?

A .mcpb file is a bundled MCP server package (similar to a Chrome extension or VS Code extension) that contains:

• The complete MCP server code

• All dependencies pre-installed

• Configuration metadata and branding

• Installation prompts for API keys

Installation Steps

Step 1: Build the Extension Package

# Clone the repository
git clone https://github.com/blencorp/capture-mcp-server.git
cd capture-mcp-server

# Install dependencies
npm install

# Create the .mcpb package
npm run package

This creates capture-mcp-server.mcpb (~4.2MB) in the current directory.

Step 2: Install in Claude Desktop

Option A: Double-click Installation

1. Locate the capture-mcp-server.mcpb file

2. Double-click the file to open with Claude Desktop

3. Click "Install" in the installation dialog

Option B: Settings Installation

1. Open Claude Desktop

2. Go to Settings → Extensions (or Developer → Edit Config)

3. Click "Install Extension..." or drag the .mcpb file into the settings window

4. Click "Install" when prompted

Step 3: Configure API Keys (Optional)

During or after installation, Claude Desktop will prompt you to configure API keys:

• Skip all keys: Click "Continue" without entering keys → 7 keyless tools available immediately

• Enter one key: Provide a SAM.gov, Tango, or HigherGov key → that provider's tools are added

• Enter all keys: All 34 tools available

You can add or update API keys later via Settings → Extensions → Capture MCP Server → Configure.

Step 4: Verify Installation

1. Restart Claude Desktop

2. Open Settings → Extensions (or Developer → MCP Servers)

3. Verify "Capture MCP Server" shows as "Connected"

4. Start a new conversation and ask: "What tools are available from Capture MCP Server?"

Important Notes for .mcpb Installation

Compatibility Warning: The .mcpb format requires Claude Desktop v1.0.0 or later. If you see errors like "This extension requires an update to Claude Desktop" or "Unrecognized key(s)", please:

1. Update Claude Desktop to the latest version, OR

2. Use Method 2: Standard MCP Configuration instead

Why Node.js? This server is built in Node.js because Claude Desktop bundles Node.js on macOS and Windows, meaning the extension works immediately without requiring users to install Python or other runtimes.

Method 2: Standard MCP Configuration (Recommended)

Standard MCP configuration is the most reliable method and works universally across all MCP clients including Claude Desktop, ChatGPT Desktop, and custom implementations.

Step 1: Clone and Build

# Clone the repository
git clone https://github.com/blencorp/capture-mcp-server.git
cd capture-mcp-server

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

This creates compiled JavaScript files in the dist/ directory.

Step 2: Locate Your MCP Configuration File

Claude Desktop (macOS):

~/Library/Application Support/Claude/claude_desktop_config.json

Claude Desktop (Windows):

%APPDATA%\Claude\claude_desktop_config.json

ChatGPT Desktop (macOS):

~/Library/Application Support/ChatGPT/mcp_config.json

ChatGPT Desktop (Windows):

%APPDATA%\ChatGPT\mcp_config.json

Note: For ChatGPT Desktop, you need a Pro, Plus, Business, Enterprise, or Education subscription. Check Settings → Beta Features → Developer Mode to enable MCP support.

Step 3: Add Server Configuration

Open your MCP configuration file and add the Capture MCP Server configuration. Choose the appropriate configuration based on which API keys you have:

Configuration A: No API Keys (7 keyless tools)

{
  "mcpServers": {
    "capture-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"]
    }
  }
}

Configuration B: SAM.gov API Key Only (13 tools)

{
  "mcpServers": {
    "capture-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"],
      "env": {
        "SAM_GOV_API_KEY": "your-sam-api-key-here"
      }
    }
  }
}

Configuration C: Tango API Key Only (16 tools)

{
  "mcpServers": {
    "capture-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"],
      "env": {
        "TANGO_API_KEY": "your-tango-api-key-here"
      }
    }
  }
}

Configuration D: HigherGov API Key Only (16 tools)

{
  "mcpServers": {
    "capture-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"],
      "env": {
        "HIGHERGOV_API_KEY": "your-highergov-api-key-here"
      }
    }
  }
}

Configuration E: All API Keys (All 34 tools)

{
  "mcpServers": {
    "capture-mcp-server": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"],
      "env": {
        "SAM_GOV_API_KEY": "your-sam-api-key-here",
        "TANGO_API_KEY": "your-tango-api-key-here",
        "HIGHERGOV_API_KEY": "your-highergov-api-key-here"
      }
    }
  }
}

Critical: Replace /ABSOLUTE/PATH/TO/capture-mcp-server with the actual absolute path to where you cloned the repository.

Examples:

• macOS: /Users/yourname/projects/capture-mcp-server

• Windows: C:\Users\yourname\projects\capture-mcp-server

Step 4: Restart Your MCP Client

• Claude Desktop: Quit completely (Cmd+Q on macOS) and reopen

• ChatGPT Desktop: Quit completely and reopen

Step 5: Verify Installation

In Claude Desktop:

1. Open Settings → Developer → MCP Servers

2. Look for "capture-mcp-server" with status "Connected"

In ChatGPT Desktop:

1. Open Settings → Beta Features → Developer Mode

2. Check MCP Servers section shows "capture-mcp-server" as "Connected"

Test the connection: Ask in a new conversation: "List all available tools from the Capture MCP Server"

You should see 7-34 tools listed depending on your API key configuration.

Method 3: Hosted Version (AWS Serverless)

Deploy a shared Capture MCP service on AWS for your organization. You deploy once, then create API keys (cap_xxx...) to distribute to your users. The serverless architecture costs ~$1-11/month and scales automatically.

Architecture

┌──────────────┐     ┌─────────────────┐     ┌──────────────┐
│  MCP Client  │────▶│  API Gateway    │────▶│    Lambda    │
│              │     │  (HTTP API)     │     │ (MCP Handler)│
└──────────────┘     └─────────────────┘     └──────┬───────┘
                                                    │
                     ┌─────────────────┐            │
                     │   S3 Bucket     │◀───────────┘
                     │  (API Keys)     │   (HeadObject for auth)
                     └─────────────────┘

Prerequisites

• AWS Account with permissions for Lambda, API Gateway, S3, CloudFormation, and IAM

• AWS CLI installed and configured (installation guide)

• Node.js 20.x or later

• AWS CDK CLI: npm install -g aws-cdk

AWS Credentials Setup

Before deploying, ensure your AWS credentials are configured. The CDK uses the same credential resolution as the AWS CLI.

Option 1: Default Profile

aws configure
# Enter your Access Key ID, Secret Access Key, and default region (e.g., us-east-1)

Option 2: Named Profile

aws configure --profile my-profile
export AWS_PROFILE=my-profile

Option 3: Environment Variables

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1

Verify your credentials are working:

aws sts get-caller-identity

Step 1: Deploy to AWS

# Install CDK dependencies
cd infrastructure
npm install
cd ..

# Bootstrap CDK (first time only per account/region)
npm run cdk:bootstrap

# Build and deploy (requires manual approval for security-sensitive changes)
npm run cdk:deploy

# Or skip approval prompts entirely (use with caution)
npm run cdk:deploy:yolo

Deploy Options:

• npm run cdk:deploy — Prompts for manual approval before creating/updating IAM roles, security groups, or other sensitive resources. Recommended for production.

• npm run cdk:deploy:yolo — Skips all approval prompts (--require-approval never). Faster for development/testing, but use with caution in production.

What is CDK Bootstrap? The first time you deploy a CDK app to an AWS account/region, you need to provision initial resources that CDK uses (S3 bucket for assets, IAM roles, etc.). This is a one-time setup. Learn more: CDK Bootstrapping

# Verify deployment succeeded - check the health endpoint
curl https://<your-api-url>/health

Step 2: Sync Configuration

After deployment, run sync-config to read the CloudFormation stack outputs and save them locally:

npm run sync-config

This creates .capture-mcp.json (gitignored) containing your deployment's bucket name, endpoint URL, and region. This is required before you can manage API keys or build the hosted extension package.

Step 3: Create API Keys for Users

Now create API keys for each user who needs access:

# Create a key that never expires
npm run manage-keys -- create --owner "John Doe"

# Create a key with an expiration date
npm run manage-keys -- create --owner "Jane Smith" --expires "2025-12-31"

Important: Save the generated key immediately! It's displayed only once and cannot be retrieved later. Keys are stored as SHA-256 hashes in S3 for security.

Key Management Commands:

npm run manage-keys -- list              # List all keys with owner and status
npm run manage-keys -- verify <key>      # Check if a specific key is valid
npm run manage-keys -- revoke <key>      # Revoke a key (by key or hash prefix)

Step 4: Build the Hosted Extension Package

Create a .mcpb file pre-configured with your endpoint URL that users can install with one click:

npm run package:hosted

This creates capture-mcp-server-hosted.mcpb containing:

• Your MCP endpoint URL (from sync-config)

• Prompts for API keys during installation

• All metadata and branding

Step 5: Distribute to Users

Option A: Provide the .mcpb File (Recommended)

Send users the capture-mcp-server-hosted.mcpb file along with their API key. They install by:

1. Double-clicking the .mcpb file to open in Claude Desktop

2. Entering their API key (cap_xxx...) when prompted

3. Optionally entering their own SAM.gov or Tango API keys for additional tools

4. Clicking Install

Option B: Manual Configuration

For users who prefer manual setup, provide them:

1. Your MCP endpoint URL (from deployment output)

2. Their personal API key (cap_xxx...)

They add this to their Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "capture-hosted": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.31",
        "https://YOUR-MCP-ENDPOINT/mcp",
        "--header",
        "X-Api-Key:cap_xxx..."
      ]
    }
  }
}

Users can add their own SAM.gov/Tango keys with additional --header arguments.

Cost Estimation

Test Your Deployment

# List available tools via curl
curl -X POST https://<your-mcp-endpoint>/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: cap_your_api_key_here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Custom Domain (Optional)

If your domain is managed as a Route53 Hosted Zone, the CDK will automatically:

• Create an ACM certificate

• Validate it via DNS (Route53)

• Create a custom domain in API Gateway

• Create an A record pointing to the API Gateway custom domain

Setup:

1. Create a .env file in the project root (copy from .env.example):

   # .env
   AWS_REGION=us-east-1
   AWS_ACCOUNT=123456789012
   DOMAIN_NAME=mcp.example.com

2. Deploy with the custom domain:

   npm run cdk:deploy

Requirement: The domain must exist as a hosted zone in Route53. For mcp.example.com, Route53 must have a hosted zone for mcp.example.com.

Updating the Deployment

To update after code changes:

npm run cdk:deploy  # Rebuilds and deploys automatically

Testing Infrastructure

The CDK stack includes comprehensive tests to verify resource configuration:

npm run cdk:test

Tests cover S3 bucket security settings, Lambda configuration, API Gateway routes and CORS, IAM permissions, CloudWatch log retention, stack outputs, and environment-specific behavior (dev vs prod).

Destroying the Stack

To remove all AWS resources:

# Prompts for confirmation before destroying
npm run cdk:destroy

# Or skip confirmation prompt entirely
npm run cdk:destroy:yolo

Destroy Options:

• npm run cdk:destroy — Prompts for confirmation before deleting resources. Recommended to prevent accidental deletion.

• npm run cdk:destroy:yolo — Skips confirmation (--force). Useful for automated teardown or when you're certain.

Note: The S3 bucket is retained by default to preserve API keys. Delete it manually if needed.

Monitoring

• CloudWatch Logs: /aws/lambda/capture-mcp-server (1 month retention)

• Key Metrics: AWS/Lambda/Invocations, AWS/Lambda/Duration, AWS/Lambda/Errors

• Custom Metrics: CaptureMCP/MCPRequestLatency

Security Notes

• API Keys: Stored as SHA-256 hashes—raw keys never persisted

• S3 Bucket: All public access blocked, SSL enforced

• Lambda IAM: Least privilege (S3 read only)

• HTTPS Only: All traffic encrypted via API Gateway

Troubleshooting

API Keys

Why Are API Keys Optional?

This server is designed with flexibility in mind:

• USASpending.gov provides a public API that requires no authentication

• SAM.gov and Tango require API keys for access to their data

You can start using the server immediately with 4 USASpending.gov tools, then add API keys later to unlock additional capabilities.

How to Get API Keys

SAM.gov API Key (Enables 6 additional tools)

Time to obtain: ~24 hours for activation

1. Create SAM.gov Account:

   • Visit https://sam.gov/content/home

   • Click "Sign In" → "Create Account"

   • Complete registration and email verification

2. Request API Access:

   • Log in to SAM.gov

   • Navigate to https://sam.gov/data-services/API

   • Click "Request Public API Key"

   • Accept terms and conditions

3. Retrieve Your API Key:

   • API key will be sent to your registered email

   • Key may take up to 24 hours to activate

   • Key is linked to your SAM.gov account

4. API Key Details:

   • Format: 64-character alphanumeric string

   • Rate Limits: Varies by endpoint (typically 1,000-10,000 requests/day)

   • Cost: Free

   • Documentation: https://open.gsa.gov/api/entity-api/

Enables these tools:

• 4 SAM.gov tools (entities, opportunities, details, exclusions)

• 2 Join tools (entity+awards, opportunity+context)

Tango API Key (Enables 12 additional tools)

Time to obtain: Immediate upon approval

1. Visit Tango Website:

   • Go to https://tango.makegov.com

2. Request Access:

   • Click "Get API Access" or "Sign Up"

   • Fill out the request form

   • Provide use case details

3. Receive API Key:

   • API key provided after account approval

   • Typically immediate for approved users

4. API Key Details:

   • Format: Variable-length string

   • Rate Limits: Check your account dashboard

   • Cost: Check pricing at https://tango.makegov.com/pricing

   • Documentation: https://tango.makegov.com/docs/

Enables these tools:

• 12 Tango tools (contracts, grants, vendor profiles, opportunities, spending summaries, protests, IDVs, vehicles, OTAs, entity metrics)

Managing API Keys

Standard MCP Configuration

Edit your MCP config file and update the env section with your keys. Restart your client after updating.

Desktop Extension (.mcpb)

1. Open Claude Desktop → Settings → Extensions

2. Click on "Capture MCP Server"

3. Click "Configure"

4. Update API key fields

5. Click "Save"

6. Claude Desktop will automatically restart the server

Security Note: Both methods store API keys securely:

• Standard config: Stored in your local config file (accessible only to you)

• Desktop extension: Stored in OS keychain (macOS/Windows credential manager)

Testing & Verification

Quick Test Queries

After installation, test that your server is working by asking these questions:

Test Without API Keys (USASpending.gov tools)

Using the Capture MCP Server, get the spending breakdown by category
for agency code 075 (Department of Health and Human Services) for
fiscal year 2024

Test SAM.gov Tools (Requires SAM_GOV_API_KEY)

Using the SAM tools, search for entities in California that work
in NAICS code 541512 (computer systems design services)

Test Tango Tools (Requires TANGO_API_KEY)

Using Tango, search for recent federal grants in renewable energy

Test Join Tools (Requires SAM_GOV_API_KEY)

Using the join tools, get both SAM entity details and award history
for UEI: KAR6JDB1HJ16

Using MCP Inspector

The MCP Inspector provides a web-based debugging interface for testing tools without Claude Desktop or ChatGPT.

Step 1: Install MCP Inspector

npm install -g @modelcontextprotocol/inspector

Step 2: Start Server with Inspector

npx @modelcontextprotocol/inspector node dist/server.js

Step 3: Open Web Interface

Navigate to http://localhost:5173 in your browser.

Step 4: Configure API Keys (Optional)

1. Click the "Environment" tab

2. Add environment variables:

   • SAM_GOV_API_KEY: your-key-here

   • TANGO_API_KEY: your-key-here

3. Restart the inspector

Step 5: Test Tools

1. View available tools (7-34 depending on API keys)

2. Click a tool to see its schema

3. Fill in parameters and click "Execute"

4. View responses and debug any issues

The Inspector is especially useful for:

• Testing new tool implementations

• Debugging API integration issues

• Understanding tool parameters and responses

• Demonstrating capabilities without Claude Desktop

Troubleshooting

Server Won't Start

Symptom: Server doesn't appear in client or shows as "Disconnected"

Solutions:

1. Verify Build:

   cd /path/to/capture-mcp-server
   npm run build

   Ensure build completes without errors.

2. Check Node.js Version:

   node --version

   Must be ≥18.0.0. Update Node.js if needed.

3. Verify Absolute Path:

   • Open your MCP config file

   • Ensure the path starts with / (macOS/Linux) or C:\ (Windows)

   • Path should NOT use ~ or environment variables

   • Path should NOT be relative (e.g., ./dist/server.js)

4. Check for Typos:

   • Verify dist/server.js exists at the specified path

   • Check JSON syntax (no trailing commas, matching braces)

5. Restart Client Completely:

   • Quit the application entirely (not just close window)

   • Reopen and check connection status

6. Check Client Logs:

   • Claude Desktop: Settings → Developer → View Logs

   • ChatGPT Desktop: Check application logs

   • Look for error messages related to "capture-mcp-server"

No Tools Appearing

Symptom: Server connects but no tools are visible

Solutions:

1. Verify API Keys (if using them):

   • Check for typos in API key values

   • Ensure no extra spaces or quotes

   • Verify keys are active (SAM.gov keys take 24 hours to activate)

2. Confirm Minimum Tool Set:

   • Without ANY keys, you should see 4 USASpending.gov tools

   • If you see 0 tools, the server isn't loading correctly

3. Test with Inspector:

   npx @modelcontextprotocol/inspector node dist/server.js

   This will show exactly which tools are loading and any errors.

4. Enable Debug Mode: Add to your env configuration:

   "env": {
     "DEBUG": "true"
   }

   Check logs for detailed error messages.

Desktop Extension (.mcpb) Installation Issues

Symptom: "This extension requires an update to Claude Desktop" or "Unrecognized key(s)"

Explanation: The .mcpb format specification has evolved. Some versions of Claude Desktop may support different manifest versions.

Solutions:

1. Update Claude Desktop (Recommended):

   • Check for updates: Settings → About

   • Update to the latest version

   • Try installing the .mcpb again

2. Use Standard MCP Configuration (Always Works):

   • Skip the .mcpb installation

   • Use Method 2: Standard MCP Configuration

   • Standard configuration is more reliable and works with all clients

3. Verify Manifest Version: If you're building from source, check manifest.json:

   "manifest_version": "0.2"

   Some Claude Desktop versions require "0.2" instead of "0.3"

4. Rebuild Package:

   npm run build
   npm run package

   Try installing the freshly built .mcpb file.

5. Check Icon File: Ensure icon.png exists in the root directory (not in subdirectories).

API Key Issues

Symptom: Tools requiring API keys return errors like "Unauthorized" or "Invalid API key"

Solutions:

1. Verify Key Validity: Test your SAM.gov API key:

   curl "https://api.sam.gov/entity-information/v3/entities?api_key=YOUR_KEY&limit=1"

   Should return JSON data, not an error.

2. Check SAM.gov Key Activation:

   • SAM.gov keys can take up to 24 hours to activate after creation

   • Wait and try again later if key is newly created

3. Remove Extra Characters:

   • API keys should have no spaces, quotes, or newlines

   • Copy key carefully from source

   • In JSON config, key should be inside quotes: "SAM_GOV_API_KEY": "abc123..."

4. Verify Key Permissions:

   • Log in to SAM.gov to check API key status

   • Ensure key has necessary permissions enabled

5. Test with MCP Inspector:

   • Use Inspector to test API calls directly

   • View exact error messages from API

ChatGPT Desktop Issues

Symptom: "MCP not available" in ChatGPT Desktop

Solutions:

1. Verify Subscription:

   • Requires Pro, Plus, Business, Enterprise, or Education subscription

   • Free tier does NOT support MCP

2. Enable Developer Mode:

   • Settings → Beta Features

   • Toggle on "Developer Mode"

3. Check ChatGPT Version:

   • Requires ChatGPT Desktop ≥1.2025.x (September 2025+)

   • Update if needed: Help → Check for Updates

4. Use Correct Config File:

   • Must be mcp_config.json (NOT claude_desktop_config.json)

   • Location: ~/Library/Application Support/ChatGPT/mcp_config.json

5. Verify JSON Structure: ChatGPT uses the same MCP config format as Claude Desktop:

   {
     "mcpServers": {
       "capture-mcp-server": { ... }
     }
   }

Rate Limiting Issues

Symptom: Tools return errors like "Too Many Requests" or "Rate limit exceeded"

Solutions:

1. Built-in Rate Limiting: This server includes automatic rate limiting:

   • SAM.gov: 100ms delay between requests

   • USASpending.gov: 3.6s delay (respects ~1000/hour limit)

   • Tango: 100ms delay between requests

2. Reduce Query Frequency:

   • Avoid rapid-fire queries

   • Use limit parameters to reduce result sizes

   • Combine queries where possible

3. Check API Quotas:

   • SAM.gov: Check your key's daily limit

   • Tango: Check your account dashboard

4. Wait and Retry:

   • Rate limits typically reset hourly or daily

   • Wait 1 hour and try again

Example Queries

Once installed, you can ask natural language questions. The LLM will automatically select and use the appropriate tools.

General Business Intelligence

Find janitorial service contracts awarded to service-disabled
veteran-owned businesses in the past 6 months

What's the total federal spending on cybersecurity contracts
in fiscal year 2023?

List all 8(a) set-aside opportunities from federal agencies
posted in the last 30 days

Agency-Specific Queries

What was the total obligated spending by HHS (Department of Health
and Human Services) on cloud computing last fiscal year?

Show me recent contract awards for 'penetration testing'
under $250,000 by the Department of Defense

Contractor Research

Find the complete profile and award history for contractor with
UEI: ZQGGHJH74DW7

Search for all IT consulting companies registered in Virginia,
then analyze their federal contract history

Market Analysis

What are the active landscaping maintenance contracts in Florida?

Show me building maintenance and repair contracts over $100,000
awarded this year across all agencies

Multi-Tool Queries

The LLM can chain multiple tools together automatically:

Find all small business contractors in NAICS 541330 (engineering
services) in Texas, then get their spending history for 2023,
and identify the top 5 by total contract value

Search for HVAC maintenance opportunities posted this month,
then analyze historical spending patterns for those agencies
to identify the most active buyers

API Documentation

Tool Reference

For complete API documentation including all parameters, schemas, and examples, see the full tool descriptions:

USASpending.gov Tools (No API key required)

• get_usaspending_awards - Get federal awards data for specific agencies

• get_usaspending_spending_by_category - Spending breakdowns by category

• get_usaspending_budgetary_resources - Budget/obligation information

• search_usaspending_awards_by_recipient - Find awards by recipient name

SAM.gov Tools (Requires SAM_GOV_API_KEY)

• search_sam_entities - Search for registered federal contractors

• get_sam_opportunities - Find contract opportunities

• get_sam_entity_details - Get comprehensive entity profiles

• check_sam_exclusions - Verify contractor eligibility status

Join Tools (Requires SAM_GOV_API_KEY)

• get_entity_and_awards - Combine SAM entity with USASpending history

• get_opportunity_spending_context - Link opportunities with spending data

Tango API Tools (Requires TANGO_API_KEY)

• search_tango_contracts - Search federal contracts (unified API)

• search_tango_grants - Search federal grants

• get_tango_vendor_profile - Get vendor profiles with full history

• search_tango_opportunities - Search opportunities with forecasts

• get_tango_spending_summary - Get spending analytics

• search_tango_protests - Search GAO bid protests with outcome filters

• get_tango_protest - Get a single protest's full record

• search_tango_idvs - Search IDIQs / BPAs / FSS vehicles that issue task orders

• get_tango_idv_children - Drill into one IDV's child IDVs, task orders, and transactions

• search_tango_vehicles - Search the federal contract-vehicle catalog (GWACs, MAS, BPAs)

• search_tango_otas - Search Other Transaction Authority (OTA) awards

• get_tango_entity_metrics - Time-series obligations for one UEI

Rate Limits

This server implements automatic rate limiting to respect API quotas:

Error Handling

All tools return structured error responses:

{
  "error": "Error message description",
  "details": "Additional context if available"
}

Common error types:

• Authentication errors: Invalid or missing API key

• Rate limit errors: Too many requests

• Validation errors: Invalid parameters

• Not found errors: Resource doesn't exist

• Server errors: API temporarily unavailable

Deploying to Railway

The server runs in HTTP mode (StreamableHTTP transport) when MCP_TRANSPORT=http. Railway is the simplest host.

1. Create a new Railway service from this repo (Nixpacks auto-detects Node).

2. Set environment variables in the Railway dashboard:

   • MCP_TRANSPORT=http (required — switches from stdio)

   • NODE_ENV=production

   • NPM_CONFIG_PRODUCTION=false (required so npm ci installs devDependencies; the build step needs tsc)

   • MCP_REQUIRE_OAUTH=true (enables the per-user authorization flow for Claude remote-connector users)

   • MCP_PUBLIC_BASE_URL=https://<your-domain> (for example, https://capture.mcp.blencorp.com)

   • OAUTH_TOKEN_SECRET=<random secret> (protects encrypted per-user provider credentials — generate with openssl rand -base64 48)

   • SAM_GOV_API_KEY, TANGO_API_KEY, and/or HIGHERGOV_API_KEY only if you want server-wide access to those tools as a fallback. Usually unset for shared deployments; each user supplies their own keys during OAuth authorization.

   • Do not set PORT — Railway injects it.

3. Deploy. Nixpacks installs dependencies, railway.toml runs npm run build, and the service starts via node dist/server.js, with healthcheck on GET /health.

4. Add a custom domain in Settings → Domains (e.g. capture.mcp.blencorp.com) and point a CNAME at the value Railway shows.

CI deploys via GitHub Actions

.github/workflows/deploy-railway.yml deploys to Railway on every push to main (and is also runnable manually from the Actions tab). One-time setup:

1. In Railway, generate a project token: Account → Tokens → Create New Token (or railway login --browserless from a workstation). Copy the token value.

2. In GitHub, add it as a repo secret: Settings → Secrets and variables → Actions → New repository secret named RAILWAY_TOKEN.

3. If Railway's built-in GitHub integration is also enabled (Service → Settings → Source), disable auto-deploys there to avoid two parallel builds racing on every push. The Action becomes the single source of truth.

The workflow installs the Railway CLI, runs railway up --service capture-mcp-server --ci, and then polls /health for up to 5 minutes to confirm the new build is serving traffic.

Auth posture

The hosted server accepts two parallel auth modes when MCP_REQUIRE_OAUTH=true:

1. OAuth (for Claude and other interactive MCP clients). POST /mcp requires a bearer token and advertises protected-resource metadata. The client redirects the user to /oauth/authorize, where the user picks which providers they have keys for (SAM.gov, Tango, HigherGov) via checkboxes and pastes the keys for those providers. The server seals all selected keys into one access token; only tools whose keys were authorized appear in the client's tool list. Keys are never exposed as tool arguments.

2. Header passthrough (for programmatic API callers). Requests that include X-Sam-Api-Key, X-Tango-Api-Key, and/or X-Highergov-Api-Key headers bypass the bearer-token gate. Only the tools whose keys are present get registered for that request. The provider key itself is the trust anchor — same model as the OAuth flow, just without the browser dance.

If MCP_REQUIRE_OAUTH is not set, HTTP mode runs unauthenticated: public USASpending tools are visible without any credential, and keyed tools light up from server env vars or request headers.

Smoke test after deploy

curl -sf https://<your-domain>/health

# 1) Unauthenticated MCP requests return 401 with a WWW-Authenticate header
#    pointing to OAuth protected-resource metadata.
curl -i https://<your-domain>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 2) Header passthrough — list HigherGov tools without going through OAuth.
curl -X POST https://<your-domain>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Highergov-Api-Key: $HIGHERGOV_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# 3) Header passthrough — call a tool directly.
curl -X POST https://<your-domain>/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Highergov-Api-Key: $HIGHERGOV_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_highergov_forecasts","arguments":{"keyword":"cyber"}}}'

After a Claude user completes OAuth authorization, tools/list returns the USASpending tools plus the provider tools enabled by that user's keys.

Development

Development Setup

# Install dependencies
npm install

# Development mode with auto-reload (uses ts-node)
npm run dev

# Build TypeScript to JavaScript
npm run build

# Run the built server
npm start

dist/ contains the compiled JavaScript output and is generated by the build step. It is intentionally gitignored—delete it before committing or packaging (rm -rf dist or rebuild) to keep the repository clean.

Building Desktop Extensions

# Build .dxt (lightweight - no node_modules, for dev/testing)
npm run package:dxt

# Build .mcpb (full bundle - includes node_modules, for distribution)
npm run package

File sizes:

• .dxt: ~19KB (just code and manifest)

• .mcpb: ~4.2MB (includes all dependencies)

Testing Tools

# Test with MCP Inspector
npm install -g @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector node dist/server.js

Project Structure

capture-mcp-server/
├── src/
│   ├── server.ts              # MCP server entry point
│   ├── tools/
│   │   ├── index.ts           # Tool registry (conditional loading)
│   │   ├── sam-tools.ts       # SAM.gov integration (4 tools)
│   │   ├── usaspending-tools.ts # USASpending integration (4 tools)
│   │   ├── tango-tools.ts     # Tango API integration (12 tools)
│   │   └── join-tools.ts      # Cross-API tools (2 tools)
│   └── utils/
│       └── api-client.ts      # HTTP client with rate limiting
├── dist/                      # Compiled JavaScript (generated, gitignored)
├── manifest.json              # Desktop Extension metadata
├── icon.png                   # Extension icon
├── package.json
└── tsconfig.json

Architecture

Server Core (src/server.ts):

• Uses @modelcontextprotocol/sdk for MCP protocol

• Stdio transport for desktop integration

• Centralized tool registration and routing

Tool Registry (src/tools/index.ts):

• Dynamically loads tool sets based on available API keys

• Enables graceful degradation when keys are missing

• Provides 7-34 tools depending on configuration

API Client (src/utils/api-client.ts):

• Centralized HTTP client with rate limiting

• Input sanitization and validation

• Consistent error handling across all APIs

• Supports GET and POST with timeouts

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Make your changes

4. Test thoroughly with MCP Inspector

5. Update documentation if needed

6. Submit a pull request

Development guidelines:

• Follow existing code style (TypeScript, ES modules)

• Add JSDoc comments for new functions

• Test all tools with Inspector before submitting

• Update README for new features

• Keep dependencies minimal

License

This project is open source under the MIT License.

Copyright (c) 2024 BLEN, Inc.

See LICENSE file for full license text.

Support

Get Help

• Issues: https://github.com/blencorp/capture-mcp-server/issues

• Discussions: https://github.com/blencorp/capture-mcp-server/discussions

• Email: Contact via https://www.blencorp.com

Useful Resources

• MCP Documentation: https://modelcontextprotocol.io/

• Claude Desktop: https://claude.ai/download

• SAM.gov API: https://open.gsa.gov/api/entity-api/

• USASpending.gov API: https://api.usaspending.gov/

• Tango API: https://tango.makegov.com/docs/

Built with ❤️ by BLEN, Inc.

About BLEN

BLEN, Inc is a digital services company that provides Emerging Technology (ML/AI, RPA), Digital Modernization (Legacy to Cloud), and Human-Centered Web/Mobile Design and Development.

Happy hunting! 🎯