mcp-payment-server

eron1703/mcp-payment-server

3.1

If you are the rightful owner of mcp-payment-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The MCP Payment Server is a token-based authentication and payment transaction system designed for AI agents, utilizing a microservices architecture to ensure security, scalability, and extensibility.

MCP Payment Server - Agent-to-Agent Payments

Token-based authentication and payment transaction system for AI agents. Built with microservices architecture, designed for security, scalability, and extensibility.

Architecture Overview

The MCP Payment Server consists of five independent microservices:

                              ┌─────────────────┐
                              │   API Gateway   │
                              │   Port: 8105    │
                              └────────┬────────┘
                                       │
                    ┌──────────────────┼──────────────────┐
                    │                  │                  │
         ┌──────────▼────────┐ ┌──────▼────────┐ ┌──────▼────────┐
         │  Auth Service     │ │Payment Service│ │ Admin Service │
         │  Port: 8101       │ │  Port: 8102   │ │  Port: 8103   │
         └──────────┬────────┘ └──────┬────────┘ └──────┬────────┘
                    │                  │                  │
                    └──────────────────┼──────────────────┘
                                       │
                              ┌────────▼────────┐
                              │Logging Service  │
                              │  Port: 8104     │
                              └─────────────────┘

Services

1. Authentication Service (Port 8101)

Validates agent identity using JWT token-based mechanism.

Endpoints:

  • POST /validate-token - Validate JWT token and return token data
  • POST /generate-token - Generate JWT token for agent (testing)
  • GET /health - Health check

2. Payment Service (Port 8102)

Manages payment creation and approval between agents.

Endpoints:

  • POST /request-payment - Create payment request from payer agent
  • POST /approve-payment - Approve or reject payment by payee agent
  • GET /payment/{payment_id} - Get payment details
  • GET /payments - Get all payments for authenticated agent
  • GET /health - Health check

3. Admin Service (Port 8103)

Configure agent budgets and permissions.

Endpoints:

  • POST /set-budget - Set or update agent budget
  • GET /get-agent-configs/{agent_id} - Get agent configuration
  • GET /get-all-agents - Get all agent configurations
  • POST /update-config - Update agent permissions
  • GET /check-budget/{agent_id} - Check if agent has sufficient budget
  • GET /health - Health check

4. Logging Service (Port 8104)

Store and provide access to transaction history.

Endpoints:

  • POST /log-transaction - Log a transaction
  • GET /transaction-history - Get transaction history with filters
  • GET /transaction/{log_id} - Get specific transaction log
  • GET /stats - Get transaction statistics
  • GET /health - Health check

5. API Gateway (Port 8105)

Routes requests to appropriate services with rate limiting.

Features:

  • Request routing to backend services
  • Rate limiting (100 requests per 60 seconds by default)
  • Service health monitoring
  • CORS enabled for all origins

Endpoints:

  • GET / - Gateway status and service URLs
  • GET /health - Health check
  • GET /services/status - Check status of all backend services
  • /auth/* - Proxy to Authentication Service
  • /payment/* - Proxy to Payment Service
  • /admin/* - Proxy to Admin Service
  • /logging/* - Proxy to Logging Service

Quick Start

1. Build and Start Services

From the project root directory:

docker-compose up -d mcp-auth-service mcp-payment-service mcp-admin-service mcp-logging-service mcp-api-gateway

2. Verify Services

Check that all services are running:

docker ps | grep mcp-

Check service health via API Gateway:

curl http://localhost:8105/services/status

3. Generate Test Token

Generate a token for agent_001:

curl -X POST "http://localhost:8105/auth/generate-token?agent_id=agent_001"

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "expires_in": 86400,
  "agent_id": "agent_001"
}

Save the access_token for subsequent requests.

4. Create Payment Request

Request a payment from agent_001 to agent_002:

curl -X POST "http://localhost:8105/payment/request-payment" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "payee_agent_id": "agent_002",
    "amount": 150.0,
    "description": "Service fee for data processing",
    "metadata": {"service": "data_processing"}
  }'

Response:

{
  "payment_id": "pay_abc123",
  "payer_agent_id": "agent_001",
  "payee_agent_id": "agent_002",
  "amount": 150.0,
  "description": "Service fee for data processing",
  "status": "pending",
  "created_at": "2025-10-26T12:00:00Z"
}

5. Approve Payment

Generate token for agent_002 and approve the payment:

# Get token for agent_002
curl -X POST "http://localhost:8105/auth/generate-token?agent_id=agent_002"

# Approve payment
curl -X POST "http://localhost:8105/payment/approve-payment" \
  -H "Authorization: Bearer AGENT_002_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "pay_abc123",
    "approved": true,
    "reason": "Services delivered successfully"
  }'

6. View Transaction History

View all transactions for an agent:

curl "http://localhost:8105/logging/transaction-history?agent_id=agent_001"

Configuration

Environment Variables

Authentication Service:

  • JWT_SECRET_KEY - Secret key for JWT signing (default: "mcp-payment-server-secret-key-change-in-production")
  • JWT_ALGORITHM - JWT algorithm (default: "HS256")
  • JWT_ACCESS_TOKEN_EXPIRE_HOURS - Token expiration in hours (default: 24)

API Gateway:

  • AUTH_SERVICE_URL - Authentication service URL
  • PAYMENT_SERVICE_URL - Payment service URL
  • ADMIN_SERVICE_URL - Admin service URL
  • LOGGING_SERVICE_URL - Logging service URL
  • RATE_LIMIT_REQUESTS - Max requests per window (default: 100)
  • RATE_LIMIT_WINDOW - Rate limit window in seconds (default: 60)

Data Models

Agent

{
  "agent_id": "agent_001",
  "name": "Processing Agent",
  "budget": 1000.0,
  "permissions": {
    "can_request_payment": true,
    "can_approve_payment": true,
    "max_transaction": 500.0
  },
  "created_at": "2025-10-26T00:00:00Z",
  "updated_at": "2025-10-26T00:00:00Z"
}

Payment

{
  "payment_id": "pay_12345",
  "payer_agent_id": "agent_001",
  "payee_agent_id": "agent_002",
  "amount": 150.0,
  "description": "Service fee for data processing",
  "status": "pending|approved|rejected|completed|failed",
  "created_at": "2025-10-26T12:00:00Z",
  "approved_at": "2025-10-26T12:05:00Z",
  "completed_at": "2025-10-26T12:05:00Z",
  "metadata": {}
}

Transaction Log

{
  "log_id": "log_12345",
  "timestamp": "2025-10-26T12:00:00Z",
  "transaction_type": "payment_request|payment_approval|payment_rejection|budget_update|config_update",
  "agent_id": "agent_001",
  "payment_id": "pay_12345",
  "details": {},
  "ip_address": "192.168.1.1",
  "user_agent": "MCP Client/1.0"
}

Security Features

  • JWT-based stateless authentication
  • Token expiration and validation
  • Budget and permission enforcement
  • Rate limiting on API Gateway
  • Transaction audit logging
  • TLS encryption ready (configure reverse proxy)

Testing

Unit Tests

Run tests for individual services:

cd mcp-payment-server/auth-service
python -m pytest tests/

cd ../payment-service
python -m pytest tests/

Integration Tests

Test the complete flow:

# Generate tokens for both agents
TOKEN_001=$(curl -s -X POST "http://localhost:8105/auth/generate-token?agent_id=agent_001" | jq -r '.access_token')
TOKEN_002=$(curl -s -X POST "http://localhost:8105/auth/generate-token?agent_id=agent_002" | jq -r '.access_token')

# Request payment
PAYMENT=$(curl -s -X POST "http://localhost:8105/payment/request-payment" \
  -H "Authorization: Bearer $TOKEN_001" \
  -H "Content-Type: application/json" \
  -d '{"payee_agent_id":"agent_002","amount":100.0,"description":"Test payment"}')

PAYMENT_ID=$(echo $PAYMENT | jq -r '.payment_id')

# Approve payment
curl -X POST "http://localhost:8105/payment/approve-payment" \
  -H "Authorization: Bearer $TOKEN_002" \
  -H "Content-Type: application/json" \
  -d "{\"payment_id\":\"$PAYMENT_ID\",\"approved\":true,\"reason\":\"Test approval\"}"

# View history
curl "http://localhost:8105/logging/transaction-history?payment_id=$PAYMENT_ID"

Monitoring and Debugging

View Logs

# View all logs
docker-compose logs -f mcp-auth-service mcp-payment-service mcp-admin-service mcp-logging-service mcp-api-gateway

# View specific service logs
docker-compose logs -f mcp-payment-service

Check Service Status

# Via API Gateway
curl http://localhost:8105/services/status

# Individual service health
curl http://localhost:8101/health  # Auth
curl http://localhost:8102/health  # Payment
curl http://localhost:8103/health  # Admin
curl http://localhost:8104/health  # Logging
curl http://localhost:8105/health  # Gateway

Development

Project Structure

mcp-payment-server/
├── shared/
│   ├── models/              # Pydantic data models
│   │   ├── agent.py
│   │   ├── payment.py
│   │   ├── token.py
│   │   └── transaction_log.py
│   └── utils/               # Shared utilities
│       ├── jwt_utils.py
│       └── logger.py
├── auth-service/
│   ├── src/
│   │   └── main.py
│   ├── tests/
│   └── Dockerfile
├── payment-service/
│   ├── src/
│   │   └── main.py
│   ├── tests/
│   └── Dockerfile
├── admin-service/
│   ├── src/
│   │   └── main.py
│   ├── tests/
│   └── Dockerfile
├── logging-service/
│   ├── src/
│   │   └── main.py
│   ├── tests/
│   └── Dockerfile
├── api-gateway/
│   ├── src/
│   │   └── main.py
│   ├── tests/
│   └── Dockerfile
├── requirements.txt
└── README.md

Adding New Features

  1. Update shared models if needed
  2. Implement service endpoints
  3. Add tests
  4. Update API Gateway routes if needed
  5. Update this README

Future Enhancements

  • External payment rail integration (Stripe, PayPal)
  • Wallet abstraction per agent
  • Multi-step approval workflows
  • Programmable payment conditions
  • Human supervisor escalation (Slack/Teams/WhatsApp integration)
  • PostgreSQL or Redis for persistent storage
  • Kubernetes deployment manifests
  • OpenAPI specification generation
  • Agent CLI for testing
  • Web UI for administration

Troubleshooting

Service won't start

# Check container status
docker ps -a | grep mcp-

# View container logs
docker logs mcp-auth-service

# Rebuild if needed
docker-compose build mcp-auth-service
docker-compose up -d mcp-auth-service

Token validation fails

  • Ensure token is included in Authorization header as "Bearer {token}"
  • Check token hasn't expired (default 24 hours)
  • Verify JWT_SECRET_KEY matches across services

Payment request fails

  • Verify agent has sufficient budget
  • Check agent permissions allow payment requests
  • Ensure payment amount doesn't exceed max_transaction limit

Services can't communicate

  • Verify all services are on flowmaster-network
  • Check docker-compose dependencies are correct
  • Ensure service URLs in environment variables use service names (not localhost)

Support

For issues or questions:

  1. Check the troubleshooting section above
  2. Review Docker logs for error messages
  3. Verify all services are healthy via /health endpoints
  4. Check transaction logs via Logging Service for audit trail

License

Internal use only - Part of FlowMaster AI Business Process Automation Platform