Environment Variables

Set via the env block in your MCP client config:

The TALONIC_API_KEY is the only required configuration. It authenticates every API call the MCP server makes on your behalf. The key must start with tlnc_ — if you pass a key with a different prefix, the server will reject it at startup with a clear error message.

The TALONIC_BASE_URL override is rarely needed. It exists for enterprise customers with a dedicated Talonic deployment or for developers testing against a staging environment. Most users should leave this unset, which defaults to https://api.talonic.com.

Environment variables are set differently depending on your MCP client and deployment mode. For local npx setups, they go in the env block of the MCP client config JSON. For the hosted server at mcp.talonic.com, the API key is passed as a Bearer token in the Authorization header instead of an environment variable.

If the MCP server cannot read the API key at startup, it exits with a descriptive error. Common causes include a malformed env block in the JSON config, a typo in the variable name, or the MCP client not passing environment variables through to the spawned process. Always fully restart the client after editing the config.

Local npx configuration example

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

Base URL override for enterprise deployments

{
  "mcpServers": {
    "talonic": {
      "command": "npx",
      "args": ["-y", "@talonic/mcp@latest"],
      "env": {
        "TALONIC_API_KEY": "tlnc_your_key_here",
        "TALONIC_BASE_URL": "https://api.talonic.yourcompany.com"
      }
    }
  }
}

For teams managing multiple environments (development, staging, production), each environment should use a separate API key pointing to a different Talonic workspace. This ensures that test documents and schemas do not mix with production data. Create separate config files or use environment-specific variable values to switch between workspaces. The TALONIC_BASE_URL override is only needed for enterprise customers with a dedicated Talonic deployment — all other users should leave it unset.

Some MCP clients support reading environment variables from the system shell rather than the config file. If your client supports this, you can set TALONIC_API_KEY in your shell profile (.bashrc, .zshrc, or equivalent) and omit the env block from the config. This approach is slightly more secure because the key is not stored in a JSON file that might be accidentally committed to version control. However, most MCP clients require the env block explicitly, so check your client's documentation.

When using the hosted server at mcp.talonic.com, environment variables are not used at all. Instead, the API key is passed in the Authorization header as a Bearer token. This means the env block is irrelevant for hosted configurations — only the url and headers fields matter. If you switch from local to hosted, remove the env, command, and args fields and replace them with url and headers.