MCP Agent Registration

MCP Agent Registration

Register an AI agent that exposes MCP tools on the Pragma.Vision ecosystem. This example covers the full flow from defining your agent’s capabilities to registering it with the platform and handling tool invocations.

Step 1: Define Your Agent Manifest

Every MCP agent needs a manifest that describes its capabilities, tools, and authentication requirements.

const agentManifest = {
  name: 'price-comparison-agent',
  display_name: 'Price Comparison Agent',
  description: 'Compares prices across multiple retailers for any product category',
  version: '1.0.0',
  protocols: ['mcp'],
  capabilities: {
    tools: [
      {
        name: 'compare_prices',
        description: 'Compare prices for a product across retailers',
        input_schema: {
          type: 'object',
          properties: {
            query: { type: 'string', description: 'Product search query' },
            category: { type: 'string', enum: ['electronics', 'books', 'clothing', 'home'] },
            max_results: { type: 'number', default: 5 },
            budget_max: { type: 'number', description: 'Maximum price filter' },
          },
          required: ['query'],
        },
      },
      {
        name: 'get_price_history',
        description: 'Get historical price data for a specific product',
        input_schema: {
          type: 'object',
          properties: {
            product_id: { type: 'string', description: 'Product identifier' },
            days: { type: 'number', default: 30, description: 'Number of days of history' },
          },
          required: ['product_id'],
        },
      },
    ],
  },
  authentication: {
    type: 'bearer',
    token_url: 'https://your-agent.example.com/auth/token',
  },
  endpoint: 'https://your-agent.example.com/mcp',
};

Step 2: Register the Agent

const response = await fetch('https://api.soft.house/agents/register', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(agentManifest),
});

const agent = await response.json();
console.log(`Agent ID: ${agent.id}`);
console.log(`Status: ${agent.status}`);
// Status will be 'pending_review' until approved

Step 3: Implement the MCP Tool Handler

Your agent endpoint must handle MCP tool invocation requests. Here is a minimal handler:

// Express.js handler for MCP tool invocations
app.post('/mcp', async (req, res) => {
  const { method, params } = req.body;

  if (method === 'tools/call') {
    const { name, arguments: args } = params;

    switch (name) {
      case 'compare_prices': {
        const results = await comparePrices(args.query, {
          category: args.category,
          maxResults: args.max_results ?? 5,
          budgetMax: args.budget_max,
        });

        return res.json({
          content: [
            {
              type: 'text',
              text: JSON.stringify(results, null, 2),
            },
          ],
        });
      }

      case 'get_price_history': {
        const history = await getPriceHistory(args.product_id, args.days ?? 30);

        return res.json({
          content: [
            {
              type: 'text',
              text: JSON.stringify(history, null, 2),
            },
          ],
        });
      }

      default:
        return res.status(400).json({
          error: { code: -32601, message: `Unknown tool: ${name}` },
        });
    }
  }

  if (method === 'tools/list') {
    return res.json({
      tools: agentManifest.capabilities.tools,
    });
  }

  res.status(400).json({
    error: { code: -32601, message: `Unknown method: ${method}` },
  });
});

Step 4: Verify Registration

// Check your agent's registration status
const statusResponse = await fetch(
  `https://api.soft.house/agents/${agent.id}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`,
    },
  }
);

const agentStatus = await statusResponse.json();
console.log(`Status: ${agentStatus.status}`);
console.log(`Tools registered: ${agentStatus.capabilities.tools.length}`);
console.log(`Invocations today: ${agentStatus.metrics?.invocations_today ?? 0}`);

Response

{
  "id": "agent_mcp_abc123",
  "name": "price-comparison-agent",
  "display_name": "Price Comparison Agent",
  "status": "active",
  "protocols": ["mcp"],
  "capabilities": {
    "tools": [
      {
        "name": "compare_prices",
        "description": "Compare prices for a product across retailers"
      },
      {
        "name": "get_price_history",
        "description": "Get historical price data for a specific product"
      }
    ]
  },
  "endpoint": "https://your-agent.example.com/mcp",
  "metrics": {
    "invocations_today": 0,
    "invocations_total": 0,
    "avg_latency_ms": null
  },
  "created_at": "2026-03-07T12:00:00Z"
}

Key Concepts

• MCP Protocol: Model Context Protocol enables AI agents to expose tools that other agents and applications can invoke
• Tool Schema: Each tool must declare its input schema using JSON Schema for type-safe invocations
• Registration Flow: Agents go through pending_review -> active status after platform verification
• Endpoint Security: Your MCP endpoint must validate the bearer token on every invocation
• Rate Limits: Registered agents are subject to rate limits based on your API tier (see Pricing)