Skip to main content

​
MCP Connection Guide

This page provides technical details for integrating Haptic’s MCP server with your AI assistant.

​
Connection URL

Production Endpoint: https://mcp.haptic.sh/mcp This single endpoint handles:
  • OAuth 2.0 authorization flow
  • Bearer token authentication
  • Tool discovery
  • Tool execution
  • Error responses

​
Authentication Methods

Haptic supports two authentication methods: Supported by: Claude Desktop, ChatGPT, and other OAuth-compatible AI assistants Flow: 
1. AI initiates connection to https://mcp.haptic.sh/mcp
2. User is redirected to Haptic's authorization page
3. User signs in with Clerk (if not already signed in)
4. User authorizes AI access to financial data
5. Haptic issues authorization code
6. AI exchanges code for access
7. Connection established
Configuration:
  • Server URL: https://mcp.haptic.sh/mcp
  • Scopes: read:accounts read:transactions
  • No API key required - handled automatically via OAuth

​
2. Bearer Token

Supported by: All MCP clients Flow: 
1. User generates token at haptic.sh/dashboard
2. User copies token (format: hap_...)
3. User configures AI with:
   - Server URL: https://mcp.haptic.sh/mcp
   - API Key: hap_...token...
4. AI includes token in Authorization header
5. Connection established
Header Format: 
Authorization: Bearer hap_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
Tool Discovery

Once connected, your AI can discover available tools via the standard MCP tools/list request.

​
Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

​
Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_account_summary",
        "description": "Get a comprehensive financial summary including account balances, net worth, assets, and liabilities breakdown",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      },
      {
        "name": "get_transactions",
        "description": "Get transactions for a custom date range across all connected accounts. When the user asks for transactions using natural language like 'last week', 'this month', 'last 30 days', etc., you must calculate the appropriate dates and convert them to YYYY-MM-DD format before calling this tool...",
        "inputSchema": {
          "type": "object",
          "properties": {
            "start_date": {
              "type": "string",
              "description": "Start date in YYYY-MM-DD format..."
            },
            "end_date": {
              "type": "string",
              "description": "End date in YYYY-MM-DD format..."
            }
          },
          "required": []
        }
      },
      {
        "name": "get_recent_transactions",
        "description": "Get transactions from the last 24 hours across all connected accounts",
        "inputSchema": {
          "type": "object",
          "properties": {},
          "required": []
        }
      }
    ]
  }
}

​
Tool Execution

Execute tools via the standard MCP tools/call request.

​
Example: get_account_summary

Request: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_account_summary",
    "arguments": {}
  }
}
Response: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Financial Summary:\n\nNET WORTH: $45,230.15\n\nASSETS ($52,000.00):..."
      }
    ]
  }
}

​
Example: get_transactions

Request: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_transactions",
    "arguments": {
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  }
}
Response: 
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Transactions (2024-01-01 to 2024-01-31):\n\n2024-01-15 | Chase Checking | Whole Foods | $125.43 (debit) | Groceries\n..."
      }
    ]
  }
}

​
Error Responses

Errors follow MCP standard error format: 
{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {
    "code": "invalid_params",
    "message": "Invalid start_date format. Please use YYYY-MM-DD format (e.g., \"2024-01-15\")."
  }
}

​
Common Error Codes

CodeMeaningCommon Causes
unauthorizedAuthentication failedInvalid or expired token
forbiddenAccess deniedNo active subscription
invalid_paramsBad parametersWrong date format, invalid tool name
tool_not_foundUnknown toolTypo in tool name
internal_errorServer errorPlaid API failure, database issue

​
Connection Examples

​
Claude Desktop

{
  "mcpServers": {
    "haptic": {
      "url": "https://mcp.haptic.sh/mcp"
    }
  }
}
Claude Desktop handles OAuth automatically - no API key needed.

​
Custom MCP Client (with token)

{
  "mcpServers": {
    "haptic": {
      "url": "https://mcp.haptic.sh/mcp",
      "headers": {
        "Authorization": "Bearer hap_your_token_here"
      }
    }
  }
}

​
Security Considerations

​
Transport Security

  • All connections use HTTPS/TLS 1.2+
  • Certificate pinning recommended for production clients
  • No unencrypted (HTTP) connections allowed

​
Token Security

DO:
  • Store tokens in secure credential stores (OS keychain, encrypted config)
  • Use environment variables for server-side applications
  • Rotate tokens periodically
DON’T:
  • Commit tokens to version control
  • Hardcode tokens in source code
  • Share tokens across environments
Tokens are sent in the Authorization header:
Authorization: Bearer hap_...
Never send tokens in:
  • URL parameters
  • Unencrypted connections
  • Log files or error messages
Immediately revoke tokens if:
  • Token is compromised or exposed
  • Device or application is lost
  • No longer using the AI assistant
Revoke via haptic.sh/dashboard

​
Request Validation

All requests are validated for:
  • ✅ Valid JSON-RPC 2.0 format
  • ✅ Authenticated user
  • ✅ Active subscription
  • ✅ Valid tool names and parameters
  • ✅ Rate limits (future)

​
Testing Your Connection

​
1. Verify Authentication

Test your token/OAuth connection: 
curl -H "Authorization: Bearer hap_your_token" \
     https://mcp.haptic.sh/mcp
Expected: Connection established or OAuth redirect

​
2. List Tools

curl -X POST https://mcp.haptic.sh/mcp \
  -H "Authorization: Bearer hap_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'
Expected: JSON response with 3 tools

​
3. Call a Tool

curl -X POST https://mcp.haptic.sh/mcp \
  -H "Authorization: Bearer hap_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "get_account_summary",
      "arguments": {}
    }
  }'
Expected: Financial summary text response

​
Troubleshooting

Symptoms: Cannot connect to https://mcp.haptic.sh/mcpSolutions:
  • Verify URL is exactly https://mcp.haptic.sh/mcp (no trailing slash)
  • Check internet connection
  • Verify HTTPS is enabled (not HTTP)
Symptoms: 401 Unauthorized errorsSolutions:
  • Verify token starts with hap_
  • Check token hasn’t been deleted from dashboard
  • Ensure active Haptic subscription
  • Try generating a new token
Symptoms: “tool_not_found” errorSolutions:
  • Verify tool name spelling (case-sensitive)
  • Use tools/list to see available tools
  • Check for typos in tool name
Symptoms: “invalid_params” errorSolutions:
  • Verify date format is YYYY-MM-DD
  • Check parameter names match documentation
  • Ensure required parameters are provided

​
MCP Specification

Haptic implements MCP v1.0 with:
  • ✅ JSON-RPC 2.0 protocol
  • ✅ Tool discovery (tools/list)
  • ✅ Tool execution (tools/call)
  • ✅ OAuth 2.0 authorization
  • ✅ Bearer token authentication
  • ✅ Structured error responses
  • ✅ Content streaming (future)
For the full MCP specification, see Model Context Protocol Docs.

​
Next Steps

MCP Tools

Explore available tools in detail

Authentication

Set up OAuth or generate tokens

API Reference

Full technical specifications

Security

Understand data protection