Agent Integration

Two ways to integrate your AI agent with UCM.

Method 1: MCP Server (Recommended)

If your agent framework supports MCP (Model Context Protocol):

{
  "mcpServers": {
    "ucm": {
      "command": "npx",
      "args": ["-y", "@ucm/mcp-server@latest"],
      "env": {
        "UCM_API_KEY": "ucm_key_..."
      }
    }
  }
}

Your agent gets 7 tools:

Tool	Description	Required Params
ucm_discover	Search for services by need	need
ucm_call	Call a service (buy + execute)	service_id, endpoint
ucm_balance	Check credit balance	—
ucm_history	Transaction history	—
ucm_service_info	Service details	service_id
ucm_register	Self-register (free, $1.00 credits)	name
ucm_list_services	Browse all services	—

No API key? Use ucm_register first — it creates one automatically and gives $1.00 credits.

See the Quick Start for full setup instructions.

Method 2: HTTP API

Base URL: https://registry.ucm.ai

Auth: Authorization: Bearer ucm_key_...

Step 1: Register

curl -X POST https://registry.ucm.ai/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

Returns an api_key and $1.00 credits. Save the API key — it is shown only once.

Step 2: Call Services

curl -X POST https://registry.ucm.ai/v1/call \
  -H "Authorization: Bearer ucm_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "ucm/web-search",
    "endpoint": "search",
    "params": { "query": "AI news" }
  }'

/v1/call atomically purchases and executes the service. Credits are refunded if the upstream call fails.

Other Useful Endpoints

# Discover services (no auth required)
curl -X POST https://registry.ucm.ai/v1/discover \
  -H "Content-Type: application/json" \
  -d '{"need": "generate images from text"}'

# Check balance
curl https://registry.ucm.ai/v1/balance \
  -H "Authorization: Bearer ucm_key_..."

# Browse service catalog (no auth required)
curl https://registry.ucm.ai/v1/services

# Transaction history
curl https://registry.ucm.ai/v1/history \
  -H "Authorization: Bearer ucm_key_..."

Decision Flow

Need an external capability?
├── Check credits (ucm_balance)
├── Credits available → Discover or list services
│   ├── Found → ucm_call (one step, auto-refund on failure)
│   └── Not found → Inform user
└── No credits → Inform user (claim at dashboard.ucm.ai for $2.00 bonus)

Getting More Credits

• Claim agent at dashboard.ucm.ai → $2.00 bonus
• Redemption codes → POST /v1/user/redeem
• Referral codes → invite other users for credits