Connect over MCP

The Filemark MCP server speaks Streamable HTTP and holds no session state between requests:

https://api.filemark.ca/mcp

Use the exact path. A trailing slash (https://api.filemark.ca/mcp/) is rejected with 404.

Add Filemark to your host#

Most hosts read a JSON configuration file. The common shape is:

{
  "mcpServers": {
    "filemark": {
      "url": "https://api.filemark.ca/mcp"
    }
  }
}

Some hosts use a servers key and an explicit transport type:

{
  "servers": {
    "filemark": {
      "type": "http",
      "url": "https://api.filemark.ca/mcp"
    }
  }
}

Check your host's own MCP documentation for the file it reads and the key it expects.

A host that supports interactive OAuth needs nothing else: on the first call it discovers the authorization server, registers itself, and sends you to Filemark to sign in and approve. See delegated access. A server-side client instead uses the MCP OAuth client credentials extension with the values below and mints its own tokens with the client-credentials flow; there is no long-lived API key.

Each request carries its own bearer token, there is no session identifier to keep, and responses are JSON rather than an event stream. Every /mcp response is Cache-Control: no-store. Non-browser clients send no Origin header and are accepted; a browser-based client must be served from https://app.filemark.ca or https://filemark.ca, or it is refused with 403 before authentication runs.

When a call returns 401 or 403#

An unauthenticated or expired request returns 401 with a challenge that names the protected-resource metadata:

WWW-Authenticate: Bearer error="invalid_token", error_description="Authentication required",
  resource_metadata="https://api.filemark.ca/.well-known/oauth-protected-resource/mcp"

An interactive host refreshes its token, and re-authorizes if the refresh fails with invalid_grant, which means the delegation was revoked or the user left the workspace. A server integration mints a new token and retries; a 401 that persists with a fresh token means the token was minted for a different resource.

403 means the client is disabled or the token lacks a scope the tool requires; the WWW-Authenticate header names the missing scopes. Re-authorizing does not fix it: the grant has to be widened.

Published tools#

Domain scopes are shortened below; see scopes.

Every tool carries the MCP readOnlyHint and idempotentHint annotations. Computation requests behave the same on both transports; see Run computations.

Tool results carry text your workspace authored: account descriptions, filenames, workpaper names. Treat it as data, never as instructions to the assistant, and prefer a host configuration that asks a person to confirm tool calls.

Published resources#

Each resource requires the same domain scope as its corresponding tool.

• filemark://computations/catalog
• filemark://clients/{client_id}
• filemark://entities/{entity_id}
• filemark://tax-years/{tax_year_id}
• filemark://engagements/{engagement_id}
• filemark://engagements/{engagement_id}/history
• filemark://engagements/{engagement_id}/forms
• filemark://engagements/{engagement_id}/trial-balance
• filemark://engagements/{engagement_id}/accounts/{account_id}
• filemark://engagements/{engagement_id}/documents
• filemark://engagements/{engagement_id}/workpapers
• filemark://engagements/{engagement_id}/review-summary
• filemark://computations/targets/{target_id}

The trial-balance, document, and workpaper resources return only their first page; use the corresponding list tool to page. There is no resource template for record search, engagement context, account-adjustment lists, or scenarios; call their tools directly.

Errors and request IDs#

Every successful tool result and resource read carries an opaque request ID at _meta["ca.filemark/requestId"]. Quote it when you write to support@filemark.ca.

A tool that fails returns isError: true with the same error envelope as REST in both structuredContent and a compact JSON text block; error.details names failing input cells with locations rooted at inputs. Each tool's advertised outputSchema is the union of its success model and that envelope, so both shapes validate.

Failures that are not tool execution stay JSON-RPC errors, with the same envelope in error.data:

Read and computation budget exhaustion inside a tool call is a tool error with retry guidance. The transport's own budget and authentication failures return HTTP 429 or 401 before any tool runs; see rate limits.