Developers

    Connect the AI tools you already use to your Batchtab account. Read-only, per account, revocable at any time.

    What you can connect

    • Claude (claude.ai, Claude desktop)
    • Claude Code
    • ChatGPT (Business and Enterprise workspaces with developer mode)
    • Claude Tag (Slack)
    • Codex
    • Cursor

    Three rules

    • Every connection is read-only.
    • Only owners and admins of an account can connect.
    • Batchtab enables the MCP endpoint per account. Until then the address answers 404.

    The address

    https://<host>/<account number>/api/mcp

    The account number is the number at the start of every Batchtab URL you open, for example /27907931/manage.

    • Protected-resource metadata (RFC 9728): https://<host>/.well-known/oauth-protected-resource/<account number>/api/mcp
    • Authorization-server metadata (RFC 8414): https://<host>/.well-known/oauth-authorization-server
    • The endpoint is stateless Streamable HTTP. It accepts POST only; other methods answer 405.

    Connect with OAuth (no key to copy)

    Sign in to Batchtab in the same browser first. The app then opens an "Allow access?" screen that names the app and the account. Press Allow.

    Access runs on one-hour keys that the app renews on its own for 30 days after last use. Owners and admins must still hold that role at renewal.

    Claude (web, desktop)

    1. Open Settings → Connectors → Add custom connector.
    2. Paste the address and choose Add.
    3. Choose Connect, then Allow.

    Claude Code

    claude mcp add --transport http batchtab https://<host>/<account number>/api/mcp

    Then run /mcp, choose batchtab, and choose Authenticate.

    ChatGPT

    1. An admin enables developer mode.
    2. Open Settings → Connectors → Create.
    3. Paste the address. Set authentication to OAuth, with no client id or secret.
    4. Choose Allow.

    Claude Tag (Slack)

    The Claude admin adds the address to a channel's access bundle with an "MCP Connector" credential and signs in once as a Batchtab owner or admin. Claude then reads as that person in that channel.

    Connect with an API token

    Use a token for tools that run on your machine and read a key from the environment.

    Create one under Settings → API Tokens → New Token with permission read. The token is shown once. The token's creator must be an owner or admin. Put it in BATCHTAB_API_TOKEN.

    Claude Code

    claude mcp add --transport http --scope user batchtab https://<host>/<account number>/api/mcp \
  --header "Authorization: Bearer $BATCHTAB_API_TOKEN"

    Codex

    In ~/.codex/config.toml: 

    [mcp_servers.batchtab]
url = "https://<host>/<account number>/api/mcp"
bearer_token_env_var = "BATCHTAB_API_TOKEN"

    Cursor

    In ~/.cursor/mcp.json: 

    {
  "mcpServers": {
    "batchtab": {
      "url": "https://<host>/<account number>/api/mcp",
      "headers": { "Authorization": "Bearer ${env:BATCHTAB_API_TOKEN}" }
    }
  }
}

    If you paste the token directly into a file, keep that file out of version control.

    Tools

    Tool names start with batchtab_, for example batchtab_search_deals.

    Every tool is annotated readOnlyHint: true, so clients can treat them as safe reads and never as writes. Only modules enabled for the account appear; disabled modules have no tools.

    Domains today:

    • Fleet: routes, deliveries, vehicles, shift plans
    • Production: plans, runs, requirements, shortages, stations
    • Projects: projects, people, organizations
    • Inventory: items, stock levels, BOM versions, attribute sets
    • Sales: deals, pricing packages
    • Purchasing: inbound documents

    Results carry a text summary and structured content. Long results are cut at a visible notice, so narrow with filters and page with limit and offset.

    The scope name is batchtab:read.

    API tokens and limits

    Tokens start with bt_ and are stored as a SHA-256 digest. Batchtab keeps the prefix, the name, the creator, and the last-used time.

    Permissions:

    • read: GET and HEAD on the JSON API, and the MCP endpoint
    • write: every JSON request
    • signal: floor-signal devices only

    Send Authorization: Bearer bt_… on every request.

    Limits: 1000 requests per minute per token, and 20 per minute for unauthenticated attempts. A 429 response carries X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After.

    Revoke a token under Settings → API Tokens. Revocation is immediate and keeps the token's history. Connected apps (OAuth) are listed on the same page with Disconnect.

    Errors

    { "error": "Invalid or expired API token", "status": 401, "code": "TOKEN_INVALID" }
    HTTP code meaning
    401 TOKEN_INVALID Revoked, expired, or unknown token.
    401 TOKEN_AUDIENCE_MISMATCH An OAuth token used outside the MCP address it was issued for.
    403 TOKEN_PERMISSION_INSUFFICIENT A write or signal token on the MCP endpoint, or a read token on a write request.
    403 ADMIN_REQUIRED The token's creator is not an owner or admin.
    404 (no code) The account has no MCP endpoint enabled, or the record does not exist on the JSON API.
    405 (no code) A method other than POST on the MCP endpoint.
    422 (no code) A JSON write failed validation. errors lists each field with its message.
    429 RATE_LIMITED Over a limit. Wait for Retry-After.

    A 401 on the MCP endpoint carries WWW-Authenticate: Bearer resource_metadata="…", scope="batchtab:read" so OAuth clients can start the flow.

    For agents

    • llms.txt (summary)
    • llms-full.txt (full)
    • The MCP endpoint's tools/list is the live catalog for one account.