TrollerBk MCP Server

Overview

Point your assistant at one URL and it can answer the questions PACER cannot: what filed this week, which sectors are moving, and which cases match the report we built for you. Every answer links to the case, the docket, and the court PDF.

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.

Every custom report on your subscription shows up as a tool named custom_<report>. Ask for it by name.

Looking up a single case you already know?

BankruptcyObserver has a free-tier MCP for exact-name and case-number lookups: mcp.bankruptcyobserver.com/docs. TrollerBk MCP is subscriber-only and starts from the national event feed. Start a trial at trollerbk.com/trial.

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 — API token as Bearer header

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: [email protected]
X-API-Key: <your-api-token>

Both schemes resolve to the same credential. The API token is under Your Account → API Token after you log in. For AI clients, prefer OAuth 2.1 so the assistant never holds that long-lived token.

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 ten tools listed above, every custom report on your subscription shows up as a tool named custom_<report> after you authenticate. Ask for it by name.

• Tool names are a URL-safe slug of the report name (e.g. custom_claims, custom_docket_events, custom_gcf_finalreport).
• Most custom tools accept start_date, end_date, limit, and (where relevant) claim_id.
• Results include both human-readable text and structuredContent.

Custom tools appear only after you authenticate with a token on that subscription. If you do not see yours in tools/list, check that the API token is active and belongs to the right account. Reports in the subscriber portal continue to work independently of MCP.

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 client: Claude, ChatGPT, Cursor, Claude Desktop, mcp-remote, or your own agent. Two auth options:

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/login and copy your API token from Your Account → API Token.
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: tools appear but will not run

• Start a fresh conversation after connecting, with the TrollerBk connector toggled on.
• In ChatGPT Settings (Connectors), confirm TrollerBk is enabled for that chat.
• If nothing executes, try Claude Desktop, Cursor, or npx mcp-remote with the same token. If those return data, the server is fine and the issue is ChatGPT-side.
• You do not need a separate execution URL. https://mcp.trollerbk.com/mcp handles tools/call.

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 under Your Account → API Token after logging in at trollerbk.com/login.

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 [email protected].