Examples & Tutorials

Examples
See It in Action

Practical examples for connecting to and using the OpenAgent Core — from initial setup to real conversations with financial data.

ConnectionsTool CallsSetup FlowConversations
Connection Examples

Connecting to the MCP Server

Three ways to connect — pick the one that fits your stack.

Claude Desktop

mcpServers config

claude_desktop_config.json
{
  "mcpServers": {
    "basiq-financial": {
      "url": "https://your-mcp-server.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer sk_live_your_tenant_api_key"
      }
    }
  }
}

Python

PydanticAI / MCP client

connect.py
import httpx

MCP_URL = "https://your-mcp-server.workers.dev/mcp"
HEADERS = {
    "Authorization": "Bearer sk_live_your_tenant_api_key",
    "Content-Type": "application/json"
}

async with httpx.AsyncClient() as client:
    # Initialize
    await client.post(MCP_URL, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 1,
        "method": "initialize",
        "params": {
            "protocolVersion": "2024-11-05",
            "capabilities": {}
        }
    })
    # List tools
    response = await client.post(MCP_URL, headers=HEADERS, json={
        "jsonrpc": "2.0", "id": 2,
        "method": "tools/list"
    })

cURL

Single tool call

terminal
curl -X POST https://your-mcp-server.workers.dev/mcp \
  -H "Authorization: Bearer sk_live_your_tenant_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_user",
      "arguments": {
        "email": "user@example.com"
      }
    }
  }'
Recommended

Code Execution Connection

Present the MCP server as a code API. The agent loads tools on-demand and processes data in the execution environment — dramatically reducing token usage.

mcp-client.ts
const MCP_URL = process.env.MCP_SERVER_URL || "https://your-mcp-server.workers.dev/mcp";
const TENANT_API_KEY = process.env.TENANT_API_KEY;

export async function callMCPTool<T>(
  toolName: string,
  args: Record<string, unknown>
): Promise<T> {
  const response = await fetch(MCP_URL, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${TENANT_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: crypto.randomUUID(),
      method: "tools/call",
      params: { name: toolName, arguments: args },
    }),
  });
  const result = await response.json();
  if (result.error) throw new Error(result.error.message);
  return JSON.parse(result.result?.content?.[0]?.text || "{}");
}
Full Code Execution Guide
Common Tool Calls

Usage Examples

The most frequently used tools — ready to copy and adapt.

create_user

Register a new user

{
  "method": "tools/call",
  "params": {
    "name": "create_user",
    "arguments": {
      "email": "jane@example.com",
      "mobile": "+61412345678"
    }
  }
}

generate_consent_url

Get bank authorization URL

{
  "method": "tools/call",
  "params": {
    "name": "generate_consent_url",
    "arguments": {
      "userId": "usr_abc123xyz",
      "callbackUrl": "https://myapp.com/callback"
    }
  }
}

get_transactions

Fetch transactions with filters

{
  "method": "tools/call",
  "params": {
    "name": "get_transactions",
    "arguments": {
      "userId": "usr_abc123xyz",
      "from": "2025-01-01",
      "to": "2025-01-31",
      "limit": 50
    }
  }
}

get_financial_health_score

Get user's health score

{
  "method": "tools/call",
  "params": {
    "name": "get_financial_health_score",
    "arguments": {
      "userId": "usr_abc123xyz"
    }
  }
}
First-Time Setup

End-to-End Onboarding Flow

From user creation to connected bank accounts — the complete sequence.

StepToolPurpose
1create_userRegister user, get userId
2generate_consent_urlGet URL for user to authorize bank
3Out of bandUser completes consent in browser
4check_consent_statusPoll until job completes
5get_accountsVerify connections, list accounts
6get_transactionsFetch transaction history
Code Execution

TypeScript Example

onboard.ts
import * as users from "./servers/basiq-financial/users";
import * as consent from "./servers/basiq-financial/consent";
import * as accounts from "./servers/basiq-financial/accounts";

async function onboardNewUser(email: string) {
  // 1. Create user
  const user = await users.createUser({ email });
  console.log(`User created: ${user.userId}`);

  // 2. Generate consent URL
  const { consentUrl } = await consent.generateConsentUrl({
    userId: user.userId,
    callbackUrl: "https://myapp.com/callback"
  });
  console.log(`Send user to: ${consentUrl}`);

  // 3. (User authorizes in browser — use webhooks or polling)
  // 4. After consent: fetch accounts
  const accountsList = await accounts.getAccounts({
    userId: user.userId
  });
  console.log(`Connected ${accountsList.length} accounts`);

  return {
    userId: user.userId,
    consentUrl,
    accounts: accountsList
  };
}
User Perspective

Conversations in Action

How end users interact with an AI assistant backed by the OpenAgent Core. The AI uses tools under the hood — users see natural conversation.

Personal Finance Assistant

Grocery Spending

What did I spend on groceries last month?

↳get_transactions

You spent $342.50 on groceries last month across 8 transactions. Your largest purchase was $89 at Woolworths on the 15th.

Health Score

How's my financial health?

↳get_financial_health_score

Your financial health score is 78/100. You're saving 22% of your income, which is strong. One area to watch: dining out spending is up 15% compared to last month.

Spending Breakdown

Break down my spending by category for January

↳get_transactions

January Spending

Groceries$342
Transport$156
Dining$289
Utilities$120
Other$95
Total$1,002

First-Time Bank Setup

Onboarding Flow

I want to connect my bank so you can help me track my spending.

↳basiq://first-time-setup

I'll help you connect your bank. This takes about 2–3 minutes and is secure — your credentials never pass through our systems.

First, I need your email to create your account.

jane@example.com

↳create_user→generate_consent_url

Done. Next, please open this link to authorize access to your bank accounts. You'll sign in with your bank's credentials on their secure page. When you're finished, come back here and tell me.

[User completes consent in browser]

I've finished connecting my bank.

↳check_consent_status→get_accounts

Your accounts are connected. I can see your everyday and savings accounts. Would you like a spending summary for this month, or help with something else?

More Scenarios

Business Expenses

Show me all expenses over $500 this quarter

↳get_transactions

Expenses over $500

1. Office supplies (Jan 5)$1,200
2. Software sub (Jan 15)$850
3. Client dinner (Feb 2)$620
4. Equipment (Feb 20)$1,500
Total (4 transactions)$4,170
Troubleshooting

My bank connection isn't showing my latest transactions

↳get_connections→sync_connection

I've triggered a sync for your bank connection. It usually takes 30–60 seconds. I'll check the status and let you know when it's done.

Related Documentation

Continue Learning

Dig deeper into each area of the OpenAgent Core.

AI Client Quick Start

Compare standard vs code execution approaches and choose the right one.

Read guide

Code Execution Guide

Full setup, file structure, and best practices for production integrations.

Read guide

Basiq Consent Flow

CDR consent process, callbacks, and error recovery detailed walkthrough.

Coming soon

MCP Protocol Reference

JSON-RPC protocol details, tool schemas, and error codes for AI clients.

Coming soon