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) is an open standard that lets AI assistants interact directly with external tools and data sources. bizSupply runs a hosted HTTP MCP server that exposes your workspace as a set of tools your assistant can call in conversation. There is nothing to install and run locally — you point your client at the hosted endpoint and authenticate with an API key.

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.

The assistant calls the bizSupply API on your behalf through the MCP tool interface, and everything stays scoped to your active organization.

Quick Start

1. Get an API Key

Create an API key via the API (or ask your bizSupply administrator to provision one):

curl -X POST "https://api.bizsupply.ai/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.ai/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.ai/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.ai/mcp",
        "headers": {
          "X-API-Key": "bsp_<your-api-key>"
        }
      }
    }
  }
}

3. Verify the Connection

Ask your AI assistant:

You should see a successful response confirming the connection.

Available Tools

Each tool maps to one or more bizSupply API endpoints. All tools are scoped to your active organization.

Public

Document Operations

Plugin Development

Pipeline Management

Job Monitoring

Ontology Management

Prompt Templates

Source Management

Benchmark & Analytics

Role Guards and Permissions

Write Operations Require ADMIN or OWNER Role

All destructive MCP tools (create, update, delete) require the authenticated user to have the ADMIN or OWNER role in their active organization. Read-only tools (list, get, search) are available to all roles.

If a user without the required role attempts a write operation, the tool returns: "Insufficient permissions. OWNER or ADMIN role required."

Platform Administrator Tools

The ontology review tools are restricted to platform administrators:

stdio Transport (for clients without native HTTP support)

For clients that do not support HTTP transport natively, use mcp-remote to bridge stdio to HTTP:

{
  "mcpServers": {
    "bizsupply": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.bizsupply.ai/mcp",
        "--header",
        "X-API-Key: bsp_<your-api-key>"
      ]
    }
  }
}

The mcp-remote package translates stdio to HTTP, allowing any MCP client to connect to the bizSupply server.

Plugin Development Workflow

The MCP integration is especially powerful for plugin development. The recommended workflow is validate → fix → register → test.

Step 1: Check the plugin interface

Ask your AI:

The AI can reference the Plugin Interface documentation.

Step 2: Write the plugin code

Work with your AI to write the plugin. The assistant has access to plugin templates, the available service methods, and best practices.

Step 3: Validate before registration

Always validate first to catch errors early:

Validation returns detailed feedback, including the offending line and a fix suggestion:

{
  "valid": false,
  "errors": [{
    "error_type": "method_not_async",
    "message": "Method 'classify' must be async",
    "severity": "error",
    "hint": "Change 'def classify' to 'async def classify'",
    "line": 5
  }]
}

Step 4: Fix and re-validate

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

Step 5: Register the plugin

Once validation passes:

The plugin then enters the platform's human-review gate before it can run.

Step 6: Test in a pipeline

Example Conversations

Once configured, you interact with bizSupply through natural language. A few examples:

List my documents

The assistant uses list_documents_filtered with the appropriate filters and presents the results in a formatted table.

Search for contracts

The assistant uses search_documents with label and content filters.

Create a classification plugin

The assistant references the plugin interface, helps write the code, validates it with validate_plugin, and registers it with create_plugin.

Monitor processing

The assistant uses list_jobs and get_job_status to report the status, progress counts, and any errors.

Authentication

API Key Authentication

API keys authenticate requests through the platform's API gateway. Two header formats are accepted:

Dedicated header (preferred):

X-API-Key: bsp_<your-api-key>

Bearer token (for clients that only support Authorization headers):

Authorization: Bearer bsp_<your-api-key>

The bsp_ prefix lets the gateway distinguish API keys from JWT tokens. When Authorization: Bearer bsp_... is detected, the request is routed through the API-key path instead of JWT validation.

API Key Format

bizSupply API keys have the format:

bsp_<opaque-key>

Example: bsp_K7xH2mN9pQ4wR6tY8uI1oL3jK5nB7vC9dE0fG1hI2jK3lM4n

Managing API Keys

Create and manage keys via the platform API (requires JWT authentication):

="color:#5c6370;font-style:italic"># Create a key (plaintext returned only once)
curl -X POST "https://api.bizsupply.ai/api/v1/api-keys" \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-ai-assistant"}'

="color:#5c6370;font-style:italic"># List keys (metadata only, no plaintext)
curl "https://api.bizsupply.ai/api/v1/api-keys" \
  -H "Authorization: Bearer <your-jwt-token>"

="color:#5c6370;font-style:italic"># Revoke a key (cannot be undone)
curl -X DELETE "https://api.bizsupply.ai/api/v1/api-keys/<key-id>" \
  -H "Authorization: Bearer <your-jwt-token>"

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 the permissions of the user who created them:

• Access to the user's documents.
• Access to the user's plugins (user scope) and the organization's plugins (tenant scope).
• Read-only access to global plugins.
• Write operations still require the ADMIN or OWNER role (same as JWT auth).

Troubleshooting

Connection failed

Symptom: the AI reports it cannot connect to bizSupply.

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

Authentication error

Symptom: tools return "unauthorized" or "invalid API key".

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

Tool not found

Symptom: the AI says a tool doesn't exist.

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

Validation errors

Symptom: plugin validation fails.

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 the base-class inheritance.

Security Considerations

The MCP server is hosted by bizSupply and reached over HTTPS using your API key. Keep the following in mind:

• Your API key is stored in your MCP client's configuration file. Ensure that file has appropriate file-system permissions.
• All communication uses HTTPS; there is no insecure HTTP option.
• The MCP server inherits the permissions of the API key you connect with. Use a key with the minimum access required for your workflow.
• Credential secrets are never returned through MCP tools — only credential names and types are visible.

Next Steps

• Plugin Interface — the 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 support@bizsupply.ai.