Content
# Capture MCP Server
An MIT-licensed, AI-native Model Context Protocol (MCP) server that integrates SAM.gov, USASpending.gov, and Tango 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 15 specialized tools that can search, analyze, and join data from multiple government APIs.
**Compatible with**: Claude Desktop, ChatGPT Desktop (Pro+), and any MCP-compatible client
## Table of Contents
- [Features](#features)
- [Tool Availability Matrix](#tool-availability-matrix)
- [Quick Start](#quick-start)
- [Installation Methods](#installation-methods)
- [Method 1: One-Click Installation (Claude Desktop)](#method-1-one-click-installation-claude-desktop)
- [Method 2: Standard MCP Configuration](#method-2-standard-mcp-configuration-recommended)
- [Method 3: Hosted Version (AWS Serverless)](#method-3-hosted-version-aws-serverless)
- [API Keys](#api-keys)
- [Testing & Verification](#testing--verification)
- [Troubleshooting](#troubleshooting)
- [Example Queries](#example-queries)
- [API Documentation](#api-documentation)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Support](#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.
### USASpending.gov Integration (4 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
### 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 (5 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
## Tool Availability Matrix
The server automatically enables tools based on which API keys you provide:
| API Keys Provided | Tool Sets Enabled | Total Tools |
| --- | --- | --- |
| **None** (works out of the box) | USASpending.gov | **4 tools** |
| `SAM_GOV_API_KEY` only | SAM.gov + USASpending.gov + Join tools | **10 tools** |
| `TANGO_API_KEY` only | Tango API + USASpending.gov | **9 tools** |
| **Both keys** | All tool sets | **15 tools** |
## 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](#api-keys) section):
- None required: 4 USASpending.gov tools work immediately
- SAM.gov API key: Adds 6 more tools (10 total)
- Tango API key: Adds 5 more tools (9 total)
- Both keys: All 15 tools
### Choose Your Installation Method
**For Claude Desktop users**: Use [Method 1: One-Click Installation](#method-1-one-click-installation-claude-desktop) for the easiest setup with a graphical API key configuration interface.
**For ChatGPT Desktop or other MCP clients**: Use [Method 2: Standard MCP Configuration](#method-2-standard-mcp-configuration-recommended) which works universally across all MCP-compatible applications.
**For hosting your own service**: Use [Method 3: Hosted Version (AWS Serverless)](#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**
```bash
# 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 → 4 USASpending.gov tools available immediately
- **Enter one key**: Provide either SAM.gov or Tango key → 9-10 tools available
- **Enter both keys**: Provide both keys → All 15 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](#method-2-standard-mcp-configuration-recommended) 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
```bash
# 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 (4 USASpending.gov tools)**
```json
{
"mcpServers": {
"capture-mcp-server": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/capture-mcp-server/dist/server.js"]
}
}
}
```
**Configuration B: SAM.gov API Key Only (10 tools)**
```json
{
"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 (9 tools)**
```json
{
"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: Both API Keys (All 15 tools)**
```json
{
"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"
}
}
}
}
```
**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 4-15 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html))
- **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**
```bash
aws configure
# Enter your Access Key ID, Secret Access Key, and default region (e.g., us-east-1)
```
**Option 2: Named Profile**
```bash
aws configure --profile my-profile
export AWS_PROFILE=my-profile
```
**Option 3: Environment Variables**
```bash
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:
```bash
aws sts get-caller-identity
```
#### Step 1: Deploy to AWS
```bash
# 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](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html)
```bash
# 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:
```bash
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:
```bash
# 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**:
```bash
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:
```bash
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):
```json
{
"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
| Usage Level | Requests/Month | Estimated Cost |
|-------------|----------------|----------------|
| Low | 100k | ~$1.11/month |
| Moderate | 1M | ~$11/month |
### Test Your Deployment
```bash
# 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`):
```bash
# .env
AWS_REGION=us-east-1
AWS_ACCOUNT=123456789012
DOMAIN_NAME=mcp.example.com
```
2. Deploy with the custom domain:
```bash
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:
```bash
npm run cdk:deploy # Rebuilds and deploys automatically
```
### Testing Infrastructure
The CDK stack includes comprehensive tests to verify resource configuration:
```bash
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:
```bash
# 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
| Problem | Solution |
|---------|----------|
| CDK deploy fails with bootstrap error | Run `npm run cdk:bootstrap` |
| "API key required" (401) | Include `X-Api-Key` header |
| "Invalid API key" (401) | Verify key with `npm run manage-keys -- verify <key>` |
| AWS credential errors | Run `aws sts get-caller-identity` to verify credentials |
| Lambda timeout | Check CloudWatch logs; some external APIs may be slow |
## 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 5 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**:
- 5 Tango tools (contracts, grants, vendor profiles, opportunities, spending summaries)
### 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](https://github.com/modelcontextprotocol/inspector) provides a web-based debugging interface for testing tools without Claude Desktop or ChatGPT.
**Step 1: Install MCP Inspector**
```bash
npm install -g @modelcontextprotocol/inspector
```
**Step 2: Start Server with Inspector**
```bash
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 (4-15 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**:
```bash
cd /path/to/capture-mcp-server
npm run build
```
Ensure build completes without errors.
2. **Check Node.js Version**:
```bash
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**:
```bash
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:
```json
"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](#method-2-standard-mcp-configuration-recommended)
- Standard configuration is more reliable and works with all clients
3. **Verify Manifest Version**:
If you're building from source, check `manifest.json`:
```json
"manifest_version": "0.2"
```
Some Claude Desktop versions require `"0.2"` instead of `"0.3"`
4. **Rebuild Package**:
```bash
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:
```bash
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:
```json
{
"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
### Rate Limits
This server implements automatic rate limiting to respect API quotas:
| API | Delay Between Requests | Daily Limit | Notes |
|-----|----------------------|-------------|-------|
| **USASpending.gov** | 3.6 seconds | ~1000 requests/hour | Public API |
| **SAM.gov** | 100ms | Varies by key | Check SAM.gov dashboard |
| **Tango** | 100ms | Varies by plan | Check Tango dashboard |
### Error Handling
All tools return structured error responses:
```json
{
"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
```bash
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
```bash
# 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
```bash
# 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
```bash
# 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 (5 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 4-15 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](https://www.blencorp.com).
## 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!* 🎯
