Getting Started with MCP

This guide walks you through connecting your AI assistant to Banked's MCP server and authenticating your requests.

PrerequisitesCopy URL

Before you begin, ensure you have:

• A Banked merchant account (sign up here)
• MCP-enabled credentials (request from support@banked.com)
• An MCP-compatible AI client (Cursor, VS Code, Claude Desktop, ChatGPT, etc.)

Step 1: Request MCP CredentialsCopy URL

Contact the Banked Customer Success team at support@banked.com to request MCP access. You'll receive:

• API Key: bk_mcp_1234567890abcdef
• Secret Key: sk_mcp_abcdef1234567890
• Allowed Scopes: Business Application IDs for your authorized applications

Step 2: Generate an Access TokenCopy URL

Before connecting to the MCP server, you need to generate an OAuth2 access token. Send a POST request to the token endpoint:

curl --location --request POST 'https://api.banked.com/oauth/token' \
--header 'Authorization: Basic base64(bk_mcp_key:sk_mcp_secret)' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=APPLICATION_ID'

You'll receive a response containing your access token:

{
  "access_token": "YOUR_MCP_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "APPLICATION_ID",
  "created_at": 1615831274
}

Step 3: Connect Your MCP ClientCopy URL

Configure your MCP client to connect to Banked's MCP server. Add the following configuration (the exact format depends on your MCP client):

{
  "mcpServers": {
    "banked": {
      "url": "https://mcp.banked.com",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
        "X-Allowed-Tools": "payments.create,payments.search,payments.refund"
      }
    }
  }
}

After adding the configuration, restart your MCP client to enable the Banked MCP server. Refer to your specific MCP client's documentation for configuration file locations and format requirements.

Step 4: Verify ConnectionCopy URL

Once configured, your AI assistant should have access to Banked's payment tools. Try asking your assistant:

"What Banked tools are available?"

You should see the following tools listed:

• payments.create - Create new payment sessions
• payments.search - Search and retrieve payments
• payments.refund - Process refunds

Example InteractionsCopy URL

Once connected, you can interact with Banked's tools through natural conversation. Here are some examples:

Creating a Payment:

"Create a $50 payment for invoice INV-2024-001"

The assistant will use payments.create and return a checkout URL. You can ask the assistant to show you the tool's parameters:

"What parameters does payments.create need?"

Searching Payments:

"Find the payment for invoice INV-123"

or

"Show me payments from last week"

The assistant will use payments.search with the appropriate filters.

Processing Refunds:

"Refund $25 from payment [payment-id]"

or

"Refund $25 from last payment"

The assistant will use payments.refund to process the refund.

Token ManagementCopy URL

Automatic Token RefreshCopy URL

For production use, implement automatic token refresh in your workflow:

async function getValidToken() {
  if (isTokenExpired(currentToken)) {
    const response = await fetch('https://api.banked.com/oauth/token', {
      method: 'POST',
      headers: {
        'Authorization': `Basic ${btoa(`${apiKey}:${secretKey}`)}`,
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: 'grant_type=client_credentials&scope=APPLICATION_ID'
    });
    
    const data = await response.json();
    currentToken = data.access_token;
  }
  return currentToken;
}

Security Best PracticesCopy URL

• Never commit tokens - Store credentials in environment variables or secure vaults
• Rotate regularly - Don't rely on tokens until expiry; rotate proactively
• Use scoped tokens - Request tokens with only the scopes you need
• Monitor usage - Review MCP activity in your Banked Dashboard

Building Autonomous AgentsCopy URL

When building agents that operate autonomously:

Consider implementing:

1. Confirmation prompts for financial operations
2. Amount limits for automated transactions
3. Audit logging for all MCP-initiated actions
4. Rate limiting to prevent runaway operations

TroubleshootingCopy URL

Connection IssuesCopy URL

Common ErrorsCopy URL

Sample AgentsCopy URL

Want to get started quickly? Clone our sample agents repository for ready-to-use sample:

The repository includes working examples that demonstrate:

• Connecting to Banked's MCP server
• Agent state management

Next StepsCopy URL

• Explore Available Tools - Learn about each MCP tool and its parameters
• Authentication Guide - Detailed OAuth2 documentation
• Payments API - Understand the underlying payment APIs