TrollerBk MCP Server

Overview

The TrollerBk MCP Server gives AI assistants direct access to TrollerBk's cross-case bankruptcy database. Unlike PACER — which requires knowing a case in advance — TrollerBk answers market-wide questions: which cases filed this week, which sectors are most active, which Chapter 11s have pending asset sales.

The server speaks JSON-RPC 2.0 over HTTPS (the MCP Streamable HTTP transport). Every request requires a valid TrollerBk API credential. There is no free tier.

Custom reporting: Subscribers with personalized custom reports registered in the TrollerBk web portal (Docket Events, Claims, GCF reports, Plans, etc.) will automatically see them exposed as additional dynamic tools (named custom_*) after authenticating. These are linked to your subscription via your API token. Web portal custom reports continue to work independently.

BKO (Bankruptcy Observer) MCP

Separate MCP server for US business bankruptcy data (filings, dockets, market intel). Free tier for exact name searches and 7-digit case numbers; all other tools require a paid MCP subscription.

BKO MCP uses the same OAuth/DCR and dual token (direct Bearer) model. mcp_users (service=bko) are authoritative and self-contained. The main bankruptcyobserver.com site subscriptions for monitoring are separate from MCP API plans.

Authentication

All requests — including initialize and tools/list — require a valid credential. Two schemes are accepted; use whichever is more convenient for your client.

Option 1 — OAuth Bearer Token (recommended)

Pass your TrollerBk API token as an Authorization header:

Authorization: Bearer <your-api-token>

Option 2 — Email + API Key Headers

Pass your registered email and API token as separate headers:

X-Client-Email: you@yourfirm.com
X-API-Key: <your-api-token>

Both schemes resolve to the same credential. The API token is available in your TrollerBk account settings at trollerbk.com/online.

Requests with missing or invalid credentials receive a JSON-RPC error with code -32001 and an HTTP 401 status.

Quick Start

1. Initialize the session

curl -X POST https://mcp.trollerbk.com/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": { "name": "my-app", "version": "1.0" },
      "capabilities": {}
    }
  }'

2. List available tools

curl -X POST https://mcp.trollerbk.com/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

3. Call a tool

curl -X POST https://mcp.trollerbk.com/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_new_filings",
      "arguments": { "days": 7, "chapter": 11, "industry": "Retail" }
    }
  }'

Available Tools

Custom Reports

In addition to the standard tools listed above, TrollerBk subscribers can access their personalized custom reports directly through the MCP.

If you have set up custom reports in the TrollerBk web portal (under Account / Custom Reports, using the legacy CustomReports register), they are automatically discovered and exposed as tools when you connect with your API token (via direct Bearer or the OAuth flow).

• Tool names are prefixed with custom_ + a URL-safe slug of the report name (e.g. custom_claims, custom_docket_events, custom_gcf_finalreport, custom_distribution).
• Most custom tools accept these arguments:
  • start_date (YYYY-MM-DD, optional)
  • end_date (YYYY-MM-DD, optional)
  • limit (integer, optional)
  • claim_id (string, for reports that require a specific claim, e.g. Traders)
• The reports you see are determined by your subscription's client record (securely linked via the API token / VwClientAuth).
• Results are returned with both human-readable text and structuredContent (same data format as the web portal).

Important: Your existing custom reports continue to work unchanged in the TrollerBk web portal (no impact on OnlineController or the public site). Custom tools are only visible/usable after successful authentication with a token that has access to them. If you don't see your customs in tools/list, double-check that your API token is active and linked to the correct subscription.

Example call (after seeing the tool in your list):

curl -X POST https://mcp.trollerbk.com/mcp \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
      "name": "custom_gcf_finalreport",
      "arguments": { "start_date": "2026-05-01", "end_date": "2026-06-01" }
    }
  }'

Response Format

All responses follow the JSON-RPC 2.0 envelope. A successful tool call returns:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      { "type": "text", "text": "{\"items\":[...],\"count\":12}" }
    ],
    "structuredContent": {
      "items": [ ... ],
      "count": 12
    }
  }
}

Errors use the standard JSON-RPC error envelope:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": { "code": -32602, "message": "Missing required argument: simple_name" }
}

Error Codes

Connecting an AI Assistant

Any MCP-compatible AI client (Claude, GPT-4o, open-source agents) can connect by adding the server URL. Two auth options are supported:

1. Direct Bearer Token (simple)

{
  "mcpServers": {
    "trbk": {
      "url": "https://mcp.trollerbk.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

2. OAuth 2.1 (recommended for AI clients)

Just point the client at the URL (no static header). The client will auto-discover OAuth metadata and run a secure PKCE authorization code flow.

{
  "mcpServers": {
    "trbk": {
      "url": "https://mcp.trollerbk.com/mcp"
    }
  }
}

Once connected, the assistant can answer investor questions directly from your conversation:

• "What retail Chapter 11s filed in the last 30 days?"
• "Search open Chapter 11 retail cases filed in Texas in the last 6 months."
• "Which open cases have 363 sale activity in Texas?"
• "Find all cases filed by EIN 12-3456789."
• "Run my custom GCF Final Report for the last month." (or any of your registered custom reports, which appear as custom_* tools)

Using OAuth 2.1 (PKCE + Bootstrap from API Token)

The TrollerBk MCP implements OAuth 2.1 (RFC 8414 / 7591 / 9708 etc.) with:

• Dynamic Client Registration (DCR)
• Authorization Code + PKCE (S256 required)
• Refresh token rotation + revocation
• Short-lived access tokens (1 hour) + longer refresh tokens

Easiest way (the "paste your token" bootstrap):

1. Log in at trollerbk.com/online and copy your API token from Account Settings.
2. Configure your MCP client with just the url (see example above). Do not hard-code a Bearer header.
3. When the client tries to connect or list tools, it will start the OAuth flow and open (or prompt for) a browser to the authorization page.
4. On the form at https://mcp.trollerbk.com/oauth/authorize (or /oauth/login), paste your existing API token and click "Authorize MCP Client". After submit you will be redirected back to complete the OAuth handshake.
5. The client receives a proper OAuth access_token (and refresh_token). Your long-lived subscription token is never sent to the AI.

For ChatGPT connector / custom OAuth forms (DCR):

• MCP Server URL / Endpoint: https://mcp.trollerbk.com/mcp
• Authorization server base URL: https://mcp.trollerbk.com (this is the issuer; ChatGPT will discover the metadata at /.well-known/oauth-authorization-server)
• Registration endpoint (if asked separately): https://mcp.trollerbk.com/oauth/register
• Token endpoint (if asked): https://mcp.trollerbk.com/oauth/token
• Authorization endpoint (if asked): https://mcp.trollerbk.com/oauth/authorize

After providing these, ChatGPT will perform DCR, then during authorization redirect you to the paste-token form where you enter your TrollerBk API token.

ChatGPT: "I can see the tools but can't invoke / execute them"

This is a common situation with ChatGPT's connector / MCP support. ChatGPT (or its internal assistant) can discover the tool catalog and schemas during the "connect" or "inspect" phase (that's why tools/list succeeds and you see custom reports), but actually making the model call the actions in a conversation is controlled by ChatGPT's UI and session state:

• Try a fresh conversation after connecting the TrollerBk connector.
• In ChatGPT Settings (Connectors, Apps, or the GPT editor if using a custom GPT), make sure TrollerBk is enabled/toggled for actions/tool use in the relevant context or GPT.
• Check whether other connected apps or built-in tools are callable in the same chat. If nothing executes, it may be a ChatGPT-side scoping or rollout limitation for that account/session (web vs desktop vs mobile can differ).
• When you connected: recent connections sometimes need a browser refresh, logout/login, or "regenerate" of the assistant response.
• You generally do not need to provide a separate "execution endpoint" URL — the /mcp endpoint (protected by the OAuth access token) is the execution point for all tools/call JSON-RPC requests.

To verify that TrollerBk's side is ready for execution (independent of ChatGPT), use a direct client (Claude Desktop, Cursor, or npx mcp-remote with your API token as Bearer) and explicitly ask it to call a tool such as get_new_filings or one of your custom_* reports. If that works and returns data, the server execution path is fine; the issue is on the ChatGPT connector activation side.

Our server logs (under the usual Laravel log) now emit detailed entries for every auth decision and every tools/call (including which client/mcp_user was attached, the exact tool name, and custom report resolution). When testing, look for trbk.mcp.post, trbk.mcp.rpc, trbk.mcp.dispatch, trbk.mcp.custom_call, etc.

Full manual flow (for custom clients, curl, or testing):

1. Discover: GET https://mcp.trollerbk.com/.well-known/oauth-authorization-server (or the /mcp/ version). Note the authorization_endpoint, token_endpoint, registration_endpoint, supported PKCE method (S256), etc.
2. (Optional but recommended) Register your client:
   POST https://mcp.trollerbk.com/oauth/register
   Body: {"client_name": "My Custom Client", "redirect_uris": ["https://example.com/callback"], "service": "trbk"}
   You get back client_id (and secret for confidential clients).
3. Start authorization: Direct the user (or open in browser) to the authorization_endpoint with query params:
   ?client_id=YOUR_ID&redirect_uri=...&response_type=code&code_challenge=BASE64URL(SHA256(verifier))&code_challenge_method=S256&state=...&scope=mcp
   (The page renders a simple form asking for your existing TrollerBk API token.)
4. After the user submits the token, you are redirected back to your redirect_uri with ?code=SHORT_LIVED_CODE&state=...
5. Exchange the code:
   POST https://mcp.trollerbk.com/oauth/token
   Form fields: grant_type=authorization_code, code=..., client_id=..., code_verifier=your-original-verifier, redirect_uri=... (add client_secret if you registered a confidential client).
6. Use the returned access_token as Authorization: Bearer <token> on all calls to https://mcp.trollerbk.com/mcp.
7. When it expires, POST to the same /oauth/token with grant_type=refresh_token + your refresh_token to get a fresh pair (old tokens are revoked on rotation).
8. Revoke anytime with POST /oauth/revoke (token=...).

The bootstrap flow (steps 3-5 above) is the main supported path today for TrollerBk subscribers who already have an API token. Full user/password or other grants are not implemented; the goal is secure token exchange from your existing subscription.

Batch Requests

The server accepts JSON-RPC batch arrays (multiple calls in one HTTP request):

[
  { "jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_cases","arguments":{"chapter":11,"status":"open"}} },
  { "jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_new_filings","arguments":{"chapter":11}} }
]

Responses are returned as a matching array.

Getting Access

MCP access is included with active TrollerBk subscriptions. Your API token (used for direct Bearer auth or to bootstrap an OAuth session) is available in Account Settings after logging in at trollerbk.com/online.

The OAuth flow (paste-token bootstrap) lets you authorize AI clients without handing them your long-lived token.

For questions, new subscriptions, or integration support, contact support@trollerbk.com.