bizSupply MCP Server

Connect your AI assistant (Claude Desktop, Cursor, Claude Code) to bizSupply using the Model Context Protocol (MCP).

What is MCP?

The Model Context Protocol (MCP) allows AI assistants to interact directly with bizSupply. Once connected, your AI can:

• Manage documents - List, search, view content and extracted data
• Develop plugins - Validate, create, update, and test plugins
• Execute pipelines - Run document processing workflows
• Monitor jobs - Track execution status and results
• Manage ontologies - Define extraction schemas
• Work with prompts - Create and manage LLM prompt templates

Quick Start

1. Get an API Key

Contact your bizSupply administrator to obtain an API key, or create one via the API:

curl -X POST "https://api.bizsupply.io/api/v1/api-keys" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-ai-assistant"}'

The response contains your API key (shown only once):

{
  "api_key": "bsp_K7xH2mN9pQ4wR6tY8uI1oL3jK5nB7vC9...",
  "name": "my-ai-assistant",
  "created_at": "2024-01-15T10:30:00Z"
}

2. Connect Your AI Client

Claude Code

claude mcp add --scope user --transport http bizsupply \
  https://api.bizsupply.io/mcp \
  --header "X-API-Key: bsp_<your-api-key>"

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bizsupply": {
      "transport": "http",
      "url": "https://api.bizsupply.io/mcp",
      "headers": {
        "X-API-Key": "bsp_<your-api-key>"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcp": {
    "servers": {
      "bizsupply": {
        "transport": "http",
        "url": "https://api.bizsupply.io/mcp",
        "headers": {
          "X-API-Key": "bsp_<your-api-key>"
        }
      }
    }
  }
}

3. Verify Connection

Ask your AI assistant:

"Use the bizsupply ping tool to check the connection"

You should see a successful response confirming the connection.

Available Tools

Public (2 tools)

Document Operations (10 tools)

Plugin Development (7 tools)

Pipeline Management (5 tools)

Job Monitoring (4 tools)

Ontology Management (6 tools)

Prompt Templates (5 tools)

Source Management (4 tools)

Benchmark & Analytics (4 tools)

Plugin Development Workflow

The MCP integration is especially powerful for plugin development. Here's the recommended workflow:

Step 1: Check Plugin Interface

Ask your AI:

"What are the requirements for a bizSupply classification plugin?"

The AI can reference the Plugin Interface documentation.

Step 2: Write Plugin Code

Work with your AI to write the plugin code. The AI has access to:

• Plugin templates and examples
• Available service methods
• Best practices

Step 3: Validate Before Registration

Always validate first to catch errors early:

"Use validate_plugin to check this classification plugin code: [your code]"

The validation returns detailed feedback:

{
  "valid": false,
  "errors": [{
    "error_type": "method_not_async",
    "message": "Method 'execute' must be async",
    "severity": "error",
    "hint": "Change 'def execute' to 'async def execute'",
    "fix_suggestion": "async def execute(self, context: PluginContext) -> None:",
    "line": 5,
    "context": [
      "   3    ",
      "   4    class MyPlugin(ClassificationPlugin):",
      "   5 ->     def execute(self, context):",
      "   6            pass"
    ]
  }]
}

Step 4: Fix and Re-validate

The AI can interpret the error and help you fix it:

"Fix the async issue and validate again"

Step 5: Register Plugin

Once validation passes:

"Create the plugin with this code"

Step 6: Test in Pipeline

"Create a pipeline with my new plugin and execute it on my documents"

Example Conversations

List My Documents

"Show me my recent documents from Gmail"

The AI will use list_documents_filtered with appropriate filters.

Search for Contracts

"Find all documents labeled as 'contract' that mention 'renewal'"

The AI will use search_documents with label and content filters.

Create a Classification Plugin

"Help me create a plugin that classifies documents as invoices, contracts, or receipts based on their content"

The AI will:

1. Reference the plugin interface requirements
2. Help write the code with proper structure
3. Validate the code using validate_plugin
4. Register it using create_plugin

Monitor Processing

"What's the status of my last pipeline execution?"

The AI will use list_jobs and get_job_status to provide details.

Authentication

API Key Format

bizSupply API keys have the format:

bsp_<base64-encoded-key>

Example: bsp_K7xH2mN9pQ4wR6tY8uI1oL3jK5nB7vC9dE0fG1hI2jK3lM4n

Security Best Practices

1. Never share your API key in public repositories or chat logs
2. Rotate keys periodically - Create new keys and revoke old ones
3. Use descriptive names - Name keys by purpose (e.g., "claude-desktop-home")
4. Revoke unused keys - Remove keys you no longer need

Key Permissions

API keys inherit permissions from the user who created them:

• Access to user's documents
• Access to user's plugins (user scope)
• Access to tenant plugins (tenant scope)
• Access to global plugins (read-only)

Troubleshooting

Connection Failed

Symptom: AI reports it cannot connect to bizSupply

Solutions:

1. Verify the API key is correct (no extra spaces)
2. Check the URL is https://api.bizsupply.io/mcp
3. Ensure your API key hasn't been revoked

Authentication Error

Symptom: Tools return "unauthorized" or "invalid API key"

Solutions:

1. Create a new API key
2. Update your AI client configuration
3. Restart your AI client

Tool Not Found

Symptom: AI says a tool doesn't exist

Solutions:

1. Verify MCP server connection with ping
2. Use server_info to list available tools
3. Check tool name spelling (use snake_case)

Validation Errors

Symptom: Plugin validation fails

Solutions:

1. Read the error message carefully - it includes fix suggestions
2. Check the Plugin Interface specification
3. Ensure all required methods are async
4. Verify base class inheritance

Next Steps

• Plugin Interface - Required plugin contract
• Create a Plugin - Step-by-step plugin development
• Plugin Service API - Available helper methods

Support

For MCP integration issues:

• Check this documentation first
• Contact your bizSupply administrator
• Email [email protected]