MCP server

Apier ships a hosted Model Context Protocol (MCP) server so an AI agent can answer Norwegian compliance questions — what a company must file, who may act for it, and when obligations are due — without you teaching it Norwegian law or rebuilding the Altinn / Maskinporten / Brønnøysund integration. The agent discovers a set of deterministic tools and calls them; every answer is the same shape it would get over REST, plus a justification an agent can cite back to a user.

The same tool verdicts are available over plain REST — see the endpoint reference. MCP is the fastest path for an agent runtime; REST is the fallback for any HTTP client.

One-click install

The quickest way in: register the Apier MCP server with your client in a single click. Cursor uses a real install deep link; Claude Desktop has no install scheme yet, so the button copies a ready-to-paste config block. Both point at the same hosted endpoint — the detailed per-client configuration below is the manual alternative, and the place to add your API key.

What you connect with

There are two ways to reach the server, and which one you use depends on your client:

• Direct streamable HTTP. Clients that speak remote MCP natively (VS Code, the OpenAI Agents SDK, Azure AI Foundry, and recent Cursor builds) connect straight to https://www.apier.no/api/mcp and send the API key in an Authorization: Bearer header.
• The @apier-no/mcp stdio proxy. Clients that only speak stdio (Claude Desktop, older Cursor) launch the published npm package via npx. It reads APIER_API_KEY from the environment, scrubs it from the child process, and forwards it as the bearer header to the same hosted endpoint. No tool logic runs locally — everything resolves server-side.

Per-client configuration

Each block below is copy-paste ready. Replace the placeholder key with a real one from your dashboard — see getting a key — and keep it out of source control.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "apier": {
      "command": "npx",
      "args": ["-y", "@apier-no/mcp"],
      "env": { "APIER_API_KEY": "apr_live_<your_key_here>" }
    }
  }
}

Restart Claude Desktop; the Apier tools appear in the tool menu.

Windows: if Claude Desktop reports spawn npx ENOENT, wrap the launcher — set "command": "cmd" and "args": ["/c", "npx", "-y", "@apier-no/mcp"], keeping the same env. The same applies to any stdio/npx-based client on Windows.

Cursor

Add the same server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "apier": {
      "command": "npx",
      "args": ["-y", "@apier-no/mcp"],
      "env": { "APIER_API_KEY": "apr_live_<your_key_here>" }
    }
  }
}

VS Code

VS Code (Copilot agent mode) speaks remote MCP natively, so it connects to the endpoint directly. Add .vscode/mcp.json:

{
  "servers": {
    "apier": {
      "type": "http",
      "url": "https://www.apier.no/api/mcp",
      "headers": { "Authorization": "Bearer apr_live_<your_key_here>" }
    }
  }
}

OpenAI Agents SDK

Wire the endpoint as a MCPServerStreamableHttp server and hand it to an Agent (Python):

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(
        name="apier",
        params={
            "url": "https://www.apier.no/api/mcp",
            "headers": {"Authorization": "Bearer apr_live_<your_key_here>"},
        },
    ) as apier:
        agent = Agent(
            name="Compliance assistant",
            instructions="Use Apier's tools for Norwegian compliance questions.",
            mcp_servers=[apier],
        )
        result = await Runner.run(agent, "What does org 999999999 owe?")
        print(result.final_output)

asyncio.run(main())

Azure AI Foundry

Register the endpoint as an MCP tool on a Foundry agent. Auth headers are passed per run and are not persisted by Foundry (Python):

from azure.ai.agents.models import McpTool

apier = McpTool(
    server_label="apier",
    server_url="https://www.apier.no/api/mcp",
)
apier.update_headers("Authorization", "Bearer apr_live_<your_key_here>")

agent = project_client.agents.create_agent(
    model="gpt-4o",
    name="compliance-assistant",
    instructions="Use Apier's tools for Norwegian compliance questions.",
    tools=apier.definitions,
)

Getting a key

Sign up and open your dashboard to create a key. It is shown in full exactly once — store it securely. Issued keys are prefixed apr_test_ (synthetic data) or apr_live_ (production). See Authentication for the full key model, tiers, and rate limits.

Try it without a key

tools/call also accepts the synthetic sandbox bearer — no signup, no key provisioning:

Authorization: Bearer apier_sandbox_test_<suffix>

Always append a unique random <suffix> (for example a fresh UUID) so your session never collides with another agent's. With a sandbox bearer, the read tools get_company_summary, get_company_context, get_company_obligations, get_company_deadlines, and explain_compliance_error answer from deterministic synthetic fixtures (every response carries _meta.is_sandbox: true), and submit_vat_return runs its usual sandbox flow. Use the reserved sandbox org numbers from GET /api/v1/sandbox/fixtures — the magic scenario pool there covers a plain active AS, a bankrupt company, an ENK, and more. Tools without a sandbox route return a deterministic SANDBOX_TOOL_UNAVAILABLE error; no sandbox call ever reaches production data or a government system.

How bearer auth works

The MCP server splits a keyless discovery surface from an authenticated call surface:

• Keyless (no key needed) — the whole handshake and discovery surface: initialize, notifications/initialized, tools/list, ping, prompts/list, prompts/get, resources/list, resources/templates/list, resources/read (public rulebook resources only), and completion/complete. A client can complete the MCP handshake and read the full catalogue before presenting any credential; the discovery response is byte-identical for every caller.
• Authenticated (key + scope) — tools/call (except the five keyless public read tools — get_public_obligations, get_public_deadlines, explain_compliance_error, get_exchange_rate, get_pricing — which execute with no credential at all, and redeem_issuance_token, which needs no API key but DOES require a credential: the one-time owner-issued issuance token in its arguments), and resources/read for company-specific resources. Otherwise a missing or invalid key returns a JSON-RPC -32001 error with a WWW-Authenticate: Bearer challenge, never a result. Each tool's required scope is in the tool reference below.

Every response also carries the negotiated MCP-Protocol-Version header — see Supported protocol versions for the full list.

The @apier-no/mcp proxy injects the bearer header for you from APIER_API_KEY; the direct-HTTP clients above set it themselves.

OAuth is coming. Today authentication is a bearer API key. An OAuth 2.1 authorization-code flow — so an agent can obtain and refresh a key without copy-pasting one — is planned for a later release. The bearer key will keep working.

Supported protocol versions

Apier negotiates the MCP protocol version during initialize and echoes the agreed value on the MCP-Protocol-Version response header. The server supports, newest first:

• 2025-11-25 (latest) — structured tool output, truthful tool annotations, per-tool icons, and verb_noun tool naming.
• 2025-06-18
• 2025-03-26
• 2024-11-05

A client that requests any of these gets it back verbatim; a client that requests an unknown version is offered the server's highest. Every newer field — title, annotations, output schema, icons — is additive, so an older client simply ignores what it does not understand.

Roadmap — not implemented. The 2026-07-28 release candidate (the Tasks extension and MCP Apps) is not supported. Its design is still changing, so Apier has deliberately not built against it; this page will be updated when that work lands.

Five-minute quickstart

1. Add the config for your client from the section above, using a real key. (No key yet? You can still explore the tool catalogue — tools/list is keyless — but calling a tool needs one.)
2. Restart the client so it picks up the new server.
3. Ask a compliance question in natural language. The agent reads the tool catalogue, picks the right tool, and calls it:

You:  What does org 999999999 owe?

Agent: (calls get_company_obligations with org_number "999999999")

      Org 999999999 has these active obligations:
      • MVA (VAT) return — filed per term — Merverdiavgiftsloven § 15-1
      • A-melding — monthly employer/payroll report — A-opplysningsloven § 3
      • Årsregnskap — annual accounts — Regnskapsloven § 8-2

      Source: Brønnøysund + Apier Universal Rulebook. Each verdict
      carries its legal_reference, so I can show you exactly which
      rule applies.

Under the hood the agent issued a single tools/call:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_company_obligations",
    "arguments": { "org_number": "999999999" }
  },
  "id": 1
}

Apier resolves it against the live Rulebook and returns the structured obligation set. 999999999 is the documentation example org; to rehearse the full authenticated surface — per-company context, dry-run filings, receipts — with zero risk and no signup, point your agent at the sandbox (it never calls a government system and tags every response _meta.is_sandbox: true).

The response envelope

tools/call returns the MCP spec CallToolResult: the tool's answer is serialized into a text content block and mirrored on structuredContent, with isError flagging failures — so the official MCP SDK client parses it without special handling:

{
  "content": [{ "type": "text", "text": "{ …the envelope below, as JSON… }" }],
  "structuredContent": {
    "result": { "...": "the normalised tool payload" },
    "justification": {
      "rules_applied": ["MVA_FILING_BIMONTHLY"],
      "source_data": ["brreg", "rulebook"],
      "valid_until": "2026-07-01T00:00:00Z"
    },
    "metadata": {
      "query_id": "…",
      "resolved_at": "2026-06-05T08:00:00Z",
      "data_sources": ["brreg", "rulebook"],
      "schema_version": "2026.6.0",
      "tool_name": "get_company_obligations"
    }
  },
  "isError": false
}

structuredContent is the same three-part envelope every tool returns, so an agent parses results uniformly. justification is the audit signal — which rules and upstream sources produced the answer, and when it goes stale. On failure, isError is true, result is null, and metadata carries a stable error_code from a closed vocabulary plus a safe error_message (never a stack trace or raw upstream body), a retryable boolean (true = repeating the same call after a short backoff can plausibly succeed; false = change the input or credential first — an identical retry fails identically), and a one-sentence remediation hint. When an upstream code had to be collapsed or renamed to keep the vocabulary closed (for example an undocumented code surfacing as UPSTREAM_UNMAPPED, or a revoked delegation surfacing as DELEGATION_REVOKED), the raw code is preserved on metadata.upstream_code.

Tool reference

26 tools are live. Names are verb_noun, so an agent can read the intent from the name alone. 22 are read-only; four model writes — submit_vat_return (a VAT return, locked to the sandbox), the two Fullmakt Rails delegation tools request_fullmakt and revoke_fullmakt (AGT-02), which broker and revoke an agent's scoped authority to act for a company through an Altinn systembruker, and redeem_issuance_token, which converts an owner-minted one-time issuance token into the agent's own API key (a write against Apier's own account state only — no government system is touched). "Live" here means the route is callable: the Fullmakt Rails writes are mock-adapter-backed pending live partner validation and make no live Altinn PDP or execution call yet.

submit_vat_return is deliberately not listed in tools/list discovery — an agent enumerating the server sees 25 tools (22 reads plus the two Fullmakt Rails delegation writes plus the keyless issuance-token redemption), and calls submit_vat_return by name when it needs the sandbox VAT flow (it stays fully callable over tools/call). The other 25 each ship a longer description, a structured output schema, truthful behaviour hints, and worked examples in their tools/list entry — clients surface these automatically.

Company intelligence

Three details of these tools are worth knowing before you wire them up:

• get_company_summary payload equivalence. Its obligations[] array is byte-identical to what get_company_obligations returns (same rule evaluation, shared cache), and its deadlines[] array matches get_company_deadlines over the same horizon for Tier 1 companies — on Tier 2 the summary's deadlines[] additionally carry a definitive filing_status (filed / overdue) from compliance state. Because the summary tool takes only { org_number }, call get_company_deadlines when you need to control horizon_months, or get_company_obligations for per-obligation drill-down.
• MOD-11 validation. For get_company_summary, get_company_context, get_company_obligations, and get_company_deadlines, a 9-digit org_number that fails the MOD-11 control-digit check is rejected up-front as VALIDATION_FAILED before any request is sent. get_company_profile is the exception: it does not run MOD-11 in its input schema, so a MOD-11 failure surfaces from the backing route as ORG_NUMBER_INVALID_CHECKSUM (HTTP 400). Either way, correct the number rather than retrying the same one.
• get_company_profile uses POST. Its backing REST route is POST /api/v1/brreg/company-profile (the org number goes in the JSON body), whereas the sibling company tools are GET /api/v1/company/{org}/…. This is a known method inconsistency — do not assume GET when falling back to raw HTTP.

Public lookups (no org number required)

Change archive

Authorisation

Delegation (Fullmakt Rails)

Actions

Billing & credits

Onboarding

The full headless onboarding journey for an agent that arrives over MCP with no credential: the account owner mints a one-time issuance token in the dashboard and hands it to the agent out-of-band → the agent calls redeem_issuance_token (keyless) and receives its own read:*-scoped API key exactly once → every subsequent call authenticates with Authorization: Bearer <plaintext_key> — starting with, say, get_credit_balance to confirm the account's balance before metered work (get_pricing needs no key at all).

Errors

Keys carry a scopes array (default read:*, which grants any read: action). A call whose key lacks the required scope returns SCOPE_INSUFFICIENT. Reserved prefixes (write:, act:, delegate:) are not assignable — which is why submit_vat_return needs only read:actions: the human approval gate, not the agent's key, authorises the mock filing.

REST-only surfaces

The MCP server exposes the read and dry-run tools an agent needs to reason about Norwegian compliance. Some Apier products are deliberately REST-only — they have no MCP tool, by design. The two surfaces are not meant to be identical: everything an agent should call autonomously is an MCP tool; everything that needs an operator, a human decision, or a financial/legal side effect stays on REST.

• Account management — creating and managing your own consumer account is an operator task behind a session, not an agent tool keyed on an API key.
• Admin / key management — minting and revoking API keys is gated by an operator secret, a different trust tier from an agent's key.
• Billing — subscription and usage endpoints are account-owner operations with financial side effects, kept off the agent surface.
• Privacy / data-subject requests — GDPR erasure and export are identity-verified human workflows, never an autonomous agent action.
• Sandbox rehearsal — the guided write-loop rehearsal is a stateful REST flow; agents reach the sandbox through the same read tools with a sandbox bearer instead.
• Human-in-the-loop approval — approving or rejecting a pending binding action is the human gate that must sit outside the agent's own credentials (the reserved act: scope is never agent-assignable).

Next steps