Connect over MCP

Connect to Filemark's MCP server at this URL.

https://api.filemark.ca/mcp

The server uses Streamable HTTP. Use /mcp without a trailing slash, as /mcp/ returns 404.

Add Filemark to your host#

Many hosts use a JSON configuration with an mcpServers key.

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

Other hosts use a servers key with an explicit transport type.

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

Check your host's MCP documentation for its configuration file and format.

Interactive OAuth hosts open Filemark for you to sign in and approve access. See delegated access for the authorization flow.

Server integrations use the MCP OAuth client credentials extension to request tokens through the client-credentials flow.

Send a bearer token with each request. The server is stateless and returns JSON with Cache-Control: no-store.

Requests with an Origin header must use https://app.filemark.ca or https://filemark.ca. Other origins return 403 before authentication. Requests without an Origin header are accepted.

When a call returns 401 or 403#

A missing or expired token returns 401 with a link to 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"

After a 401, interactive hosts should refresh the token, and server integrations should request a new one before retrying. A refresh that returns invalid_grant requires a new authorization. If a fresh token returns 401, check that its resource matches the endpoint.

For an authenticated request, 403 means the client is disabled or a required scope is missing. Check the client's status and the scopes listed in WWW-Authenticate, then update its access as needed.

Published tools#

Scopes are shortened below. See scopes.

Tools include the MCP idempotentHint annotation. Read and computation tools also include readOnlyHint. Write tools set readOnlyHint to false, and the four that reach outside Filemark set openWorldHint to true. See Run computations for computation behavior shared by REST and MCP.

Treat account descriptions, filenames, and other workspace text in tool results as untrusted data when configuring your host.

Write tools#

Write tools take the same values as REST. Pass the idempotency key as idempotencyKey, the record version as expectedResourceVersion, and a preview's token as confirmationToken. See Write data.

Published resources#

Each resource requires the same scope as its 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}
• filemark://export-jobs/{export_job_id}
• filemark://engagements/{engagement_id}/mutation-preconditions
• filemark://portal-requests/{request_id}
• filemark://integration-syncs/{sync_id}
• filemark://engagements/{engagement_id}/documents/{document_id}
• filemark://document-ingestions/{ingestion_id}
• filemark://engagements/{engagement_id}/workpapers/{workpaper_id}
• filemark://engagements/{engagement_id}/workpapers/{workpaper_id}/evidence

Trial-balance, document, and workpaper resources return the first page. Use the matching list tool for subsequent pages. Record search, engagement context, account adjustments, scenarios, and export job lists are available through tools.

Export jobs#

Call create_export with a new UUID as idempotencyKey to build an engagement's filing handoff package. Reuse the key when retrying to retrieve the same job. Poll get_export_job until status is succeeded or failed.

Use list_export_jobs to find earlier jobs for an engagement. The live API schema also describes the REST export and import-capture operations.

To export a scenario, include scenario.inputs with the overrides and, when available, the scenario computation's sourceStateSha256. The job builds a separate draft package and comparison, checks that the saved inputs, engine version and rate tables have not changed since it was created, and leaves the saved return unchanged. Its purpose is draft_scenario and its readiness is unevaluated. See Export a scenario.

A successful job returns the file name, size, SHA-256 digest, and a downloadPage URL where a signed-in Filemark user can download the package. The job expires seven days after creation.

Hosts with MCP Apps support display ui://filemark/export-panel with results from get_engagement_import_capture, create_export, and get_export_job. The panel lets users open the engagement's Documents inbox to upload a tax-software return, start an export, and open its download page. get_engagement_import_capture returns the values captured from that upload. Inbox and download links use a signed-in Filemark browser session. Other hosts receive the tool result as JSON.

Errors and request IDs#

Successful tool results and resource reads include _meta["ca.filemark/requestId"]. Include this request ID when contacting support@filemark.ca.

Failed tools return isError: true with the API error object in both structuredContent and a JSON text block. Validation errors identify cells in error.details, with paths relative to inputs. Each tool's outputSchema describes successful and failed results.

Failures outside tool execution return JSON-RPC errors with the API error object in error.data.

Read and computation limits reached during tool execution produce tool errors with retry guidance. Transport rate limits return HTTP 429, and authentication failures return 401 before execution. See rate limits.