Protocol and compatibility
InvoicePig implements MCP over Streamable HTTP at:
https://www.invoicepig.com/mcpIt natively implements the MCP specification version 2026-07-28 and provides stateless Streamable HTTP fallback for 2025-era clients. Protocol discovery depends on client version: 2025-era clients negotiate capabilities during initialization, while 2026 clients use the newer discovery flow. Clients may expose tools, prompts, and resources differently in their user interface.
Server capability matrix
| MCP feature | InvoicePig support | Notes |
|---|---|---|
| Streamable HTTP | Yes | The hosted transport. |
| OAuth 2.1 authorization | Yes | Clerk OAuth, with the profile and user:org:read scopes. The consent screen selects one workspace. |
| Protected-resource metadata | Yes | Advertised in the 401 challenge and at the standard well-known URL. |
| Client registration | Dynamic client registration (DCR) | Clerk’s authorization-server metadata currently advertises a registration endpoint; Client ID Metadata Documents are not enabled in this deployment. |
| Tools | Yes | Two stateless PDF-generation tools. |
| Prompts | Yes | Three optional guided workflows. |
| Resources | Yes | Three resources: one Markdown guide plus artifact-download and logo-manager MCP Apps UI resources. |
| Legacy SSE transport | No | Intentionally disabled. |
| Server-side OCR / URL fetching | No | The host client must read supplied sources. |
| Persistent draft or invoice management | No | Generation never writes InvoicePig history. |
The server provides concise instructions describing when to use each tool and which invoice facts an agent must confirm. Tool definitions expose typed input and output schemas plus readOnlyHint, destructiveHint, idempotentHint, and openWorldHint annotations. Generation is non-destructive but is not marked read-only or idempotent because every call publishes a new temporary artifact and signed URL. These annotations are guidance to clients, not authorization controls.
OAuth discovery endpoints
| Endpoint | Purpose |
|---|---|
/mcp | Protected MCP Streamable HTTP endpoint. |
/mcp-docs | Human-readable MCP documentation. |
/.well-known/oauth-protected-resource/mcp | Tells a client which authorization server protects the MCP endpoint. |
/.well-known/oauth-authorization-server | Authorization-server metadata for compatibility with clients that use this discovery path. |
An unauthenticated MCP request should receive 401 Unauthorized with a WWW-Authenticate: Bearer challenge that identifies the protected-resource metadata. A compatible client follows the challenge; users should not call OAuth endpoints manually during normal setup.
Prompts and resources are optional client features
MCP tools, prompts, and resources are separate capabilities. A client may show only the tools even though it successfully connects. In that case, use the tools directly and follow the payload reference; the server itself is still fully usable.
Result and error semantics
Successful tools return a short text summary for the model and the complete typed result in structuredContent. PDF and ZIP data therefore are not duplicated into the text message. Tool failures return isError: true with structured code, message, retryable, and, for HTTP failures, status fields so an agent can correct input or retry safely.
The hosted endpoint is stateless and does not issue MCP session IDs. Unauthenticated requests receive 401; authenticated session-oriented GET requests return 405, and legacy SSE routes are disabled. Protocol-version negotiation is handled by the MCP SDK rather than hard-coded by the tools.
The recommended client path is the hosted HTTP endpoint documented above. The repository also contains a Node/Bun stdio wrapper for self-hosting or advanced integrations; see the package README for that separate path.