Skip to content
MetaTana

These docs are for MetaTana 2.0, coming soon

On this page

Set Up The Local API Key (Pro)

Pro feature Using the local app API with an API key is a Pro feature. A signed-in Pro account is required for both the API key and the MCP bridge. Calls from the MetaTana web UI work without it.

The local app API (/api/v1/**) is what the MetaTana UI uses. With Pro, your own scripts, automations, and MCP-capable agents can use it too, with an API key. This recipe walks through finding the key, copying it, and making your first call.

Step 1: Confirm you're signed in with Pro

API-key access needs a verified Pro account. Open Settings › Account to check your plan. If you're not signed in or not on Pro, the API key drawer says Pro required for MetaTana API access instead of showing the key.

Settings › Maintenance with the Advanced group: MCP, Webhooks, API key, and Command-line tool.
Settings › Maintenance › Advanced

Step 2: Open the API key

Open Settings › Maintenance and find Advanced, then select Show on API key. The MetaTana API key drawer has:

  • The current key, hidden until you reveal it
  • Copy
  • Regenerate, which stops the current key from working

The MCP bridge setup is in the same group, under MCP › Set up.

Showing or regenerating the key needs Pro Revealing or regenerating the local API key always needs a verified Pro session. Release desktop and Docker builds ignore any auth-bypass environment variables, so the check can't be turned off.

Step 3: Copy the key

Reveal the key, then select Copy. Treat it like a password: anyone with the key and access to your MetaTana port can read and change your library through the API.

Step 4: Make your first call

Calls send both the API key and your Pro session:

curl http://localhost:3000/api/v1/library \
  -H "x-api-key: $METATANA_API_KEY" \
  -H "x-metatana-hosted-session: $METATANA_HOSTED_SESSION"

To see the whole API, open /api/v1/docs in your browser. The raw OpenAPI spec is at /api/v1/openapi. MCP › Set up links to both.

Step 5: Set up the MCP bridge (optional)

The MCP bridge lets MCP-capable agents (Claude Desktop, Cursor, and others) call your local MetaTana API over stdio. In Settings › Maintenance › Advanced, select MCP › Set up, copy the client setup for your platform, and add it to your MCP client's config.

The bridge checks your Pro session and adds the API key on its own. It is stricter than a direct API-key caller: it refuses changes outside library work, such as Settings writes and resets. See API reference: MCP bridge.

What success looks like

  • The API key drawer shows a real key, not the Pro notice
  • curl returns a 200 with a JSON body listing library titles
  • If you use MCP: your agent can list library titles, scrape, edit metadata, and so on

Going deeper