Tutorial: Agent Provisioning and MCP Integration

When building AI-first applications, your LLMs and autonomous agents need safe, scoped access to your tenant data. ButtrBase provides native support for Service Accounts* and the *Model Context Protocol (MCP).

1. Creating a Service Account for your Agent

Unlike standard users, agents don't log in via passwords or SSO. They use long-lived, tightly scoped Service Account keys.

Endpoint: POST /api/v2/organizations/:org_uuid/service-accounts

curl -X POST https://api.buttrbase.com/api/v2/organizations/org-uuid-123/service-accounts   -H "Authorization: Bearer "   -H "Content-Type: application/json"   -d '{
    "name": "Claude Data Extraction Bot",
    "role_id": 12,
    "expires_in_days": 365
  }'

The response will contain an access_key (e.g., bb_svc_...). Save this securely, as it will not be shown again.

2. Token Metering for AI Usage

AI models charge by the token. You can pass these costs down to your tenants automatically using the Metering API.

import { ButtrBaseClient } from '@buttrbase/js-sdk';
const client = new ButtrBaseClient('https://api.buttrbase.com');
client.setToken('bb_svc_your_agent_key');
// After your LLM finishes generation:
await client.billing.recordUsage({
  org_uuid: "org-uuid-123",
  meter_name: "claude_3_5_sonnet_tokens",
  quantity: 4520, // Prompt + Completion tokens
  action: "increment"
});

3. Exposing Data via MCP

If you are using Cursor, Claude Code, or another MCP-compatible client, you can connect ButtrBase directly so the LLM can query your organizations, users, and audit logs.

In your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "buttrbase": {
      "command": "npx",
      "args": ["-y", "@buttrbase/mcp-server"],
      "env": {
        "BUTTRBASE_SVC_TOKEN": "bb_svc_your_agent_key",
        "BUTTRBASE_ORG_UUID": "org-uuid-123"
      }
    }
  }
}

Your AI can now seamlessly read and interact with your SaaS backend!