Getting Started

Get your first BPMCP agent running in just a few minutes.

Get your first BPMCP agent running in 5 minutes.

Prerequisites

Node.js 18+ or Python 3.8+
An API key from bpmcp.dev
Basic understanding of APIs and async programming

Installation

Choose your preferred method:

NPM Package (Recommended)


npm install @bpmcp/sdk

Direct API Access


# No installation needed - just use your API key
export BPMCP_API_KEY="bpmcp_your_api_key_here"

MCP Server for Claude Desktop


npm install -g @bpmcp/mcp-server

Get Your API Key

Visit bpmcp.dev/dashboard
Sign in with GitHub or Google
Click “Create API Key”
Copy your key (starts with bpmcp_)

Your First Process Call

Let’s make your first call to discover available processes:


import { BPMCP } from '@bpmcp/sdk';
 
// Initialize the client
const bpmcp = new BPMCP({
  apiKey: process.env.BPMCP_API_KEY
});
 
// List available processes
async function discoverProcesses() {
  // Get all P2P (Procure-to-Pay) processes
  const processes = await bpmcp.processes.list({
    domain: 'p2p'
  });
 
  console.log('Available P2P processes:');
  processes.forEach(process => {
    console.log(`- ${process.id}: ${process.name}`);
    console.log(`  Phases: ${process.phases.length}`);
    console.log(`  Providers: ${process.providers.join(', ')}`);
  });
}
 
discoverProcesses();

Expected output:


Available P2P processes:
- corporate-cards: Corporate Card Expenses
  Phases: 5
  Providers: payhawk, brex, ramp
- invoices: Invoice Processing
  Phases: 5
  Providers: sap, netsuite, quickbooks

Understanding Process Structure

Every process follows the Five Moves Framework:


// Get detailed process information
const cardProcess = await bpmcp.processes.get('p2p/corporate-cards');
 
console.log('Process Structure:');
cardProcess.phases.forEach((phase, index) => {
  console.log(`Phase ${index + 1}: ${phase.name}`);
  phase.atoms.forEach(atom => {
    console.log(`  - ${atom.id}: ${atom.description}`);
  });
 
  if (cardProcess.flows[index]) {
    console.log(`Flow ${index + 1}: ${cardProcess.flows[index].name}`);
  }
});

Execute Your First Atom

Now let’s execute a specific business action:


// Execute an atom (business action)
const result = await bpmcp.atoms.execute({
  processId: 'p2p/corporate-cards',
  atomId: 'attach-receipt',
  input: {
    expenseId: 'exp_123',
    receiptImage: 'base64_encoded_image_data'
  }
});
 
console.log('Receipt attached:', result.success);
console.log('Next suggested action:', result.nextAtom);

Using with MCP (Model Context Protocol)

If you’re building an agent that uses MCP:


// List available tools for a specific phase
const tools = await bpmcp.mcp.listTools({
  process: 'p2p/corporate-cards',
  phase: 'capture'
});
 
// Execute via MCP protocol
const mcpResult = await bpmcp.mcp.call({
  tool: 'payhawk.attach_receipt',
  input: {
    expenseId: 'exp_123',
    file: 'receipt.pdf'
  }
});

Next Steps

Now that you have the basics working:

Understand the Five Moves Framework - Learn how every business process is structured
Explore Process Discovery - Find the right process for your use case
Build Your First Agent - Step-by-step tutorial for a complete agent
Integrate with Claude Desktop - Connect BPMCP to Claude

Quick Tips

API Keys: Keep your API key secure, never commit it to git
Rate Limits: Free tier allows 100 requests/minute
Environments: Use different API keys for dev/staging/prod
Debugging: Set BPMCP_DEBUG=true for detailed logs
Support: Join our Discord for help

Common Issues

”Invalid API Key”

Make sure your key starts with bpmcp_ and is active in the dashboard.

”Process not found”

Check available processes first with bpmcp.processes.list()

”Provider not available”

Some providers require additional setup. Check the provider docs.

”Rate limit exceeded”

Free tier is limited to 100 req/min. Consider upgrading or implementing backoff.

Example: Quick Expense Submission

Here’s a complete example that submits an expense:


import { BPMCP } from '@bpmcp/sdk';
 
async function submitExpense() {
  const bpmcp = new BPMCP({
    apiKey: process.env.BPMCP_API_KEY
  });
 
  // Start the corporate cards process
  const session = await bpmcp.sessions.create({
    process: 'p2p/corporate-cards'
  });
 
  // Phase 1: Capture
  await bpmcp.atoms.execute({
    sessionId: session.id,
    atomId: 'capture-expense',
    input: {
      amount: 42.50,
      merchant: 'Coffee Shop',
      date: '2024-03-15'
    }
  });
 
  // Flow 1: Validation
  await bpmcp.flows.transition({
    sessionId: session.id,
    flowId: 'validate-expense'
  });
 
  // Phase 2: Enrich
  await bpmcp.atoms.execute({
    sessionId: session.id,
    atomId: 'add-category',
    input: {
      category: 'meals'
    }
  });
 
  // Continue through remaining phases...
 
  console.log('Expense submitted successfully!');
}
 
submitExpense();

Ready to dive deeper? Check out our comprehensive tutorials or explore the API reference.