DrillerDB Enterprise MCP API

openapi: 3.2.0
info:
  title: DrillerDB Public Enterprise MCP API
  version: '2026-10-07'
  summary: Well data, driller directory, and DrillerDB application APIs
  description: 'Machine-readable description of every public DrillerDB endpoint, in three groups, each with its own server:


    1. drillerdb.com: free, unauthenticated JSON endpoints (well depth and water-table lookup, driller directory and license search, ZIP geocoding, platform stats, conference calendars). Errors are {error, message}. An /api path with no endpoint answers 404, and a method an endpoint does not support answers 405 with an Allow header; both bodies add hint and documentation (ApiRoutingError).

    2. app.drillerdb.com/api/v1: read-only access to a DrillerDB customer''s own projects, invoices, work orders, contacts, equipment and inventory. Requires an X-API-Key issued to an Enterprise-plan company; each key carries scopes and each operation names the scope it needs in x-required-scope. Errors are {error:{code,message,hint}, meta:{request_id}, links}.

    3. enterprise.drillerdb.com/api/mcp: Model Context Protocol server for DrillerDB Enterprise (prospect intelligence), OAuth 2.1 with the mcp:read:enterprise scope.


    Rate limits on drillerdb.com: 500 requests per IP address per 60 seconds, counted across page views and API requests together, not per endpoint. Every /api response the limiter counted carries RateLimit-Policy and RateLimit (draft-ietf-httpapi-ratelimit-headers-11); a 429 also carries Retry-After in seconds.


    Versioning and deprecation: the keyed APIs carry their major version in the path (app.drillerdb.com/api/v1, console.drillerdb.com/api/partner/v1). Additive changes, such as new fields, new optional parameters and new operations, stay in the current version; a breaking change ships under a new major version path. A deprecated version says so on every response with the Deprecation header (RFC 9745), the Sunset header (RFC 8594) and a Link header with rel="deprecation". At least 12 months pass between the date a version first sends the Deprecation header and its Sunset date. No version is deprecated today. Details: https://drillerdb.com/docs/integrations/api-conventions.


    Any HTML page on drillerdb.com can be fetched as Markdown with Accept: text/markdown. Site index for agents: https://drillerdb.com/llms.txt.'
  termsOfService: https://drillerdb.com/terms
  contact:
    name: DrillerDB
    url: https://drillerdb.com/contact-us
    email: support@drillerdb.com
servers:
- url: https://drillerdb.com
  description: drillerdb.com public endpoints (no key)
tags:
- name: Enterprise MCP
  description: Model Context Protocol server for DrillerDB Enterprise (enterprise.drillerdb.com)
paths:
  /api/mcp:
    servers:
    - url: https://enterprise.drillerdb.com
      description: DrillerDB Enterprise (OAuth 2.1)
    post:
      tags:
      - Enterprise MCP
      operationId: callEnterpriseMcp
      summary: Enterprise MCP server (Streamable HTTP transport)
      description: 'Model Context Protocol endpoint for DrillerDB Enterprise customers: drilling-company prospect data, lead scores, saved lists, territories and market signals, exposed as MCP tools. Connect an MCP client to this URL; it discovers the OAuth server from the WWW-Authenticate header on the first 401 and from /.well-known/oauth-protected-resource. GET on the same path opens the server-to-client event stream and DELETE ends a session, per the MCP Streamable HTTP transport. Human setup guide: https://enterprise.drillerdb.com/docs.'
      security:
      - EnterpriseMcpOAuth:
        - mcp:read:enterprise
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JsonRpcRequest'
      responses:
        '200':
          description: JSON-RPC response, as application/json or as a text/event-stream of JSON-RPC messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonRpcResponse'
            text/event-stream:
              schema:
                type: string
        '401':
          description: 'Missing or invalid token. WWW-Authenticate: Bearer realm="enterprise-mcp", error=..., resource_metadata="https://enterprise.drillerdb.com/.well-known/oauth-protected-resource".'
          headers:
            WWW-Authenticate:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpAuthError'
components:
  schemas:
    JsonRpcRequest:
      type: object
      description: A JSON-RPC 2.0 request as defined by the Model Context Protocol.
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
        id:
          type:
          - string
          - integer
          - 'null'
        method:
          type: string
          description: MCP method, e.g. initialize, tools/list, tools/call.
        params:
          type: object
      required:
      - jsonrpc
      - method
    McpAuthError:
      type: object
      properties:
        error:
          type: string
          description: OAuth error code, e.g. missing_token, invalid_token.
        error_code:
          type: string
      required:
      - error
    JsonRpcResponse:
      type: object
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
        id:
          type:
          - string
          - integer
          - 'null'
        result:
          type: object
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
            data: {}
          required:
          - code
          - message
      required:
      - jsonrpc
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Company API key issued in DrillerDB Settings > API Access (Enterprise plan). Keys are scoped; the scopes a key may hold are projects:read, invoices:read, work_orders:read, contacts:read, equipment:read and inventory:read. A key lacking the scope an operation needs receives 403 INSUFFICIENT_SCOPE with meta.required_scope.
    EnterpriseMcpOAuth:
      type: oauth2
      description: 'OAuth 2.1 authorization-code flow with PKCE (S256), as published at https://enterprise.drillerdb.com/.well-known/oauth-authorization-server. Dynamic client registration is available at https://enterprise.drillerdb.com/oauth/register. Tokens are presented as Bearer in the Authorization header. Protected-resource metadata (RFC 9728): https://enterprise.drillerdb.com/.well-known/oauth-protected-resource.'
      flows:
        authorizationCode:
          authorizationUrl: https://enterprise.drillerdb.com/oauth/authorize
          tokenUrl: https://enterprise.drillerdb.com/oauth/token
          refreshUrl: https://enterprise.drillerdb.com/oauth/token
          scopes:
            mcp:read:enterprise: Read drilling-company prospect data, lead scores, lists, territories, and market signals on the user's behalf (read-only).
externalDocs:
  description: When to use DrillerDB and how an agent calls us (llms.txt)
  url: https://drillerdb.com/llms.txt
x-generated-by: scripts/build-openapi.mjs
x-legacy-spec-source: https://app.drillerdb.com/api/v1/openapi.json