MarkDocket Documentation

MarkDocket is a full-stack IP intelligence platform covering trademark search, patent research, prior-art analysis, USPTO filing submissions, portfolio management, and AI-assisted drafting. Everything runs from a single TypeScript monorepo that ships six distinct packages, each with a clearly bounded role.

Platform components

The table below describes every package and how it relates to the others.

How data flows

At a high level, every action in MarkDocket travels through markdocket-api — no surface writes directly to the database or speaks to worker siblings without going through it first.

Browser (markdocket)
  └─▶ markdocket-api  (REST / SSE, cookie or API key)
        ├─▶ Neon Postgres  (sole writer via Drizzle ORM)
        ├─▶ markdocket-agent  (delegated JWT)
        │     └─▶ AI Gateway / BYOK worker  ──▶ LLM providers
        │           └─▶ tool calls back to markdocket-api  (delegated token)
        ├─▶ USPTO worker  (HMAC-signed webhooks)
        ├─▶ brand-intel worker  (HMAC-signed webhooks)
        ├─▶ Inngest  (durable background functions)
        ├─▶ Stripe + billing-meter worker
        └─▶ Vercel Blob  (vault, figure, and artifact storage)

markdocket-cli / hosted MCP
  └─▶ markdocket-api /v1/tools  (personal API key)
       or  /mcp  (OAuth 2.1 access token)

markdocket-landing
  └─▶ markdocket-api /api/blog, /api/help, /api/contact, /api/newsletter

Authentication surfaces

MarkDocket supports six distinct authentication modes. All of them — except the hosted MCP, /v1/tools, and device-token paths — ultimately resolve to a Better Auth user row managed by markdocket-api.

The tool catalog — one source of truth

The platform's entire tool surface is defined once and derived everywhere. markdocket-cli/src/catalog.ts imports the agent's tool registry and from it generates:

• CLI commands (markdocket call <tool-name>)
• The stdio MCP server's registered tools
• The /v1/tools REST gateway
• The hosted /mcp Streamable HTTP endpoint

Adding a tool to the agent's registry makes it automatically available across all four surfaces — no separate registration is needed. MCP behavioral hints (readOnlyHint, idempotentHint, destructiveHint) are derived from HTTP method metadata already present on each tool definition, not from a separately maintained annotation list.

The billing contract

@markdocket/customer-pricing-contract is the shared billing and pricing library imported by all four main packages. Its central type, BillingBlockEnvelope, flows as a first-class validated value across every layer:

• HTTP 402 body from markdocket-api
• billing_required SSE event from markdocket-agent
• Inngest automation signal (AutomationBillingBlockSignal) from background runs
• Browser pub/sub that triggers a billing modal in the web app
• CliToolError in the CLI with human-readable output
• structuredContent error in the MCP server

A shared parseBillingBlockEnvelope validator handles the envelope at every boundary — including recovery from cross-process serialization where JavaScript instanceof checks no longer hold. This means billing enforcement surfaces consistently in any client, regardless of how it reached the platform.

Pricing itself is never hardcoded. The web app and landing site both fetch the live pricing catalog from markdocket-api at SSR time. If the catalog is unavailable, both surfaces render a disabled state rather than showing stale prices.

Access methods

Web dashboard

Sign in at app.markdocket.com. The dashboard provides agent chat, portfolio and deadline tracking, trademark and patent search, AI-assisted drafting, automated workflow runs, a file vault, and billing management.

CLI

Install the public npm package:

npm install -g @markdocket/cli

Authenticate with a browser login (OAuth 2.1) or a personal API key:

markdocket login          # opens browser for OAuth 2.1 flow
markdocket login --api-key YOUR_KEY

Run any tool from the catalog:

markdocket call trademark_search --input '{"query":"Acme Widget"}'

See the CLI documentation for the full command reference.

MCP server (stdio)

The same @markdocket/cli package ships a stdio MCP server usable from any MCP-compatible host (Claude Desktop, Cursor, and similar):

# In your MCP host configuration, point to:
markdocket mcp

The stdio MCP server and the hosted /mcp Streamable HTTP endpoint expose the same catalog-derived tool set.

Hosted MCP endpoint

The hosted MCP endpoint lives at markdocket-api/mcp and accepts OAuth 2.1 access tokens. Dynamic client registration (RFC 7591) is supported — no static client ID needs to be distributed. The OAuth 2.1 authorization server metadata is discoverable at /.well-known/oauth-authorization-server.

Personal API keys and /v1/tools

Personal API keys created in the dashboard can be used with the /v1/tools REST gateway. All tool calls via API key require an Idempotency-Key header for write-mutating operations; the platform deduplicates replays automatically.

Background processing

Long-running work — trademark draft research, patent drafting, due-diligence reports, automation workflow runs, and webhook delivery — executes as durable Inngest functions. Each node in an automation graph runs inside its own checkpointed step, so a process restart resumes from the last completed step rather than from the beginning. Async USPTO and brand-intel jobs use event-driven waits rather than polling loops, with a two-hour per-step timeout.

Usage billing events are written to a transactional outbox in Postgres and drained asynchronously with lease-based FOR UPDATE SKIP LOCKED claiming, exponential backoff retries, and dead-lettering for permanently failed rows. This means billing events are never lost due to a process crash and do not require an external message broker.

Bring Your Own Key (BYOK)

Users can configure their own AI provider keys in account settings. BYOK keys are stored encrypted and are available only within agent nodes inside Automation Runs — they are not used for interactive agent chat, draft workflows, or any other direct LLM call. The web app's BYOK settings section makes this scope explicit.

Desktop companion

The MarkDocket Desktop companion is a separate native application (not part of this package) that pairs with the web app via a one-time code and deep link. Once paired, it can run supervised USPTO form-filling submissions in your own local Chrome browser. The web dashboard shows live status, screenshots, and a recovery path for any step that requires user intervention.

Where to go next

• Set up the CLI — see the CLI installation and authentication guide
• Connect an MCP client — see the MCP quickstart
• Manage a portfolio — see portfolio and deadline tracking
• Build an automation — see the automation canvas and node reference
• Review pricing and billing — see the billing and usage documentation
• Integrate with your tools — see calendar, Slack, Asana, Google Drive, and other integrations