Install Overview

Three ways to connect. The recommended path for Claude.ai users is the hosted MCP via the OAuth connector flow: paste one URL into Claude.ai's connector settings, sign in with your Talonic account, approve the consent screen. No API key in your config, ever. For IDE-style clients (Cursor, Cline, Continue, Cowork) and Claude Desktop, the local npx install is the canonical path. A third hosted option, with the Talonic API key in an Authorization header, exists for clients that support custom headers on remote MCP servers.

Hosted via Claude.ai connector (OAuth, recommended)

Claude.ai's Add custom connector flow does the OAuth 2.1 handshake for you. The MCP server lives at https://mcp.talonic.com/mcp; Claude.ai discovers the authorization server, registers itself dynamically (RFC 7591), and runs the PKCE authorization-code flow. The resulting access token is stored by Claude.ai and refreshed automatically (1-hour access token, 30-day refresh).

Open https://claude.ai/settings/connectors.
Click Add custom connector.
URL: https://mcp.talonic.com/mcp — no query string, no headers.
Click Connect. You are redirected to Talonic to sign in.
Sign in with Google, Microsoft, or your company SSO.
Approve the consent screen. The requested scopes are extract:write, documents:read, and schemas:read. Pick a workspace if you have multiple.
You are returned to Claude.ai with the connector live. All eight tools are available in any new conversation.

No API key appears in the connector config or in any URL the browser navigates to. To revoke access, remove the connector in Claude.ai or revoke the OAuth client from your Talonic dashboard. Your tools and tokens are scoped to the workspace you picked at consent time.

Local stdio (npx)

Recommended for IDE-style clients (Cursor, Cline, Continue, Cowork) and Claude Desktop, where the MCP host spawns the server as a local child process. Requires Node.js 18+. Your API key lives in the client's env block.

Local config

{
  "command": "npx",
  "args": ["-y", "@talonic/mcp@latest"],
  "env": { "TALONIC_API_KEY": "tlnc_..." }
}

The -y flag skips the npm install prompt. Pinning to @latest means new versions are picked up on the next client restart. For production deployments and CI, pin to a specific version (e.g. @talonic/mcp@0.1.27) so a future release cannot silently change tool descriptions, validation rules, or response shapes.

Hosted with a Bearer header (custom-header clients)

For MCP clients that support remote servers with custom headers (mcp-inspector, custom integrations), connect to the hosted endpoint with the API key in an Authorization header. Claude.ai's connector UI does not currently support custom headers, which is why the OAuth flow above is the recommended path for Claude.ai users.

Hosted config (custom-header clients)

{
  "url": "https://mcp.talonic.com/mcp",
  "headers": { "Authorization": "Bearer tlnc_..." }
}

All three install paths expose the same eight tools and two resources. The hosted server runs the latest version of @talonic/mcp automatically; the local npx install picks up the latest version on next client restart when pinned to @latest.

Verify the connection

After adding the config and restarting your MCP client, verify the connection by asking the agent to list your schemas. This is a lightweight read-only call that confirms the API key is valid and the server is reachable. If the call succeeds, all eight tools are ready to use.

Verification: ask the agent to call talonic_list_schemas

// Agent sends:
{ }

// Server responds (empty workspace):
{
  "schemas": []
}

// Server responds (workspace with saved schemas):
{
  "schemas": [
    {
      "id": "sch_7a1b...",
      "short_id": "SCH-A1B2C3D4",
      "name": "Standard Invoice",
      "field_count": 6
    }
  ]
}

If the verification fails, check three things in order: (1) your JSON config is syntactically valid — a missing comma or bracket is the most common cause, (2) the API key starts with tlnc_ and has not been revoked, and (3) you fully restarted the MCP client after editing the config. For the local npx option, you can also test the server standalone by running npx -y @talonic/mcp@latest --version in a terminal to confirm it installs and prints a version number.

The hosted and local options can be swapped at any time by editing your config. Some developers start with the hosted option for quick setup and switch to local npx when they need offline access or want to inspect server logs. The tools, parameters, and responses are identical regardless of which option you choose, so no agent-side changes are needed when switching.

If you are behind a corporate proxy or firewall that blocks outbound HTTPS to mcp.talonic.com, use the local npx option and configure your proxy via standard HTTPS_PROXY environment variables.

Frequently asked questions

How do I install the Talonic MCP server?+

Use the hosted server at mcp.talonic.com/mcp — just set the URL and your API key in any MCP client config. No install needed. Alternatively, run locally via npx @talonic/mcp.

What is the difference between hosted and local MCP server?+

Both expose the same tools and resource. Hosted requires zero local dependencies and auto-updates. Local runs on your machine via npx and requires Node.js 18+. Latency is comparable since both call the same API.

Do I need to update the MCP server manually?+

With the hosted server, updates are automatic. With the local npx option, pinning to @latest means new versions are fetched on the next client restart.

Can I switch between hosted and local without changing my workflow?+

Yes. Both options expose identical tools, parameters, and responses. Edit the config to swap between hosted URL and local npx command, restart the client, and everything works the same. No agent-side or schema changes needed.

What Node.js version do I need for the local option?+

Node.js 18 or later. The npx command downloads and runs the MCP server package automatically. No global install is needed — npx handles it. Run node --version in a terminal to check your version.

Claude Desktop

Cursor