Use ACE from your IDE with MCP

ACE (Agentic Commerce Engine) runs inside any app that speaks the Model Context Protocol (MCP). Once connected, your assistant can read the ACE documentation and call ACE tools directly: run the Contextual Enrichment Engine, track jobs, score a feed, manage webhooks, and work with Google Merchant Center, without leaving your editor.

This guide is for people who use ACE at https://ace.authoritas.com and want to plug it into Cursor, VS Code, Claude Code, or another MCP client.

What is MCP and why use it with ACE?

MCP is a standard way for AI assistants to talk to external services. Connecting ACE means:

• Your assistant can read the ACE docs, so it answers questions and writes integration code from the current documentation rather than guesswork.
• Your assistant can call ACE, so "enrich these products for Google Shopping and tell me when the job finishes" becomes one instruction rather than a script you write first.

Which tools are available is controlled per project under Settings, Developer console, MCP.

Where to connect

ACE MCP server URL: https://ace.authoritas.com/api/mcp

It is a streamable HTTP MCP server. Listing tools is public, so a client can connect and discover the catalogue with no key. Calling a tool requires an API key in the Authorization header.

The fastest path is the Connect section under Settings, Developer console, MCP: one-click install buttons for Cursor and VS Code, a copy-paste command for Claude Code, and a config block with your key already filled in. A machine-readable server card is published at https://ace.authoritas.com/.well-known/mcp.json.

Step 1: Get an API key

Use the same key you use for the REST API.

1. Log in at https://ace.authoritas.com.
2. Go to Settings, Developer console, Keys.
3. Create a key with the scopes for the tools you plan to call. An ace_test_ key is free and quota-capped, which makes it ideal for a first connection. An ace_live_ key runs against your account for real.

Scopes are enforced on every tool call, so give the key what it needs:

New keys get enrichment:read, enrichment:write, and utils:read. Add webhooks:write if you want the webhook tools. See API Keys.

Step 2: Add the server in Cursor

1. Open Settings, MCP.
2. Click Add new MCP server.
3. Set the URL to https://ace.authoritas.com/api/mcp.
4. Add a header. Name: Authorization. Value: Bearer <your-api-key>.
5. Save, and restart Cursor if prompted.

Or by config, in ~/.cursor/mcp.json or your project's .cursor/mcp.json:

{
  "mcpServers": {
    "ace": {
      "url": "https://ace.authoritas.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Step 3: Add the server in VS Code

For GitHub Copilot Agent or another MCP-capable extension, add .vscode/mcp.json:

{
  "servers": {
    "ace": {
      "type": "http",
      "url": "https://ace.authoritas.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Reload VS Code as your extension requires.

Step 4: Claude Code, other clients, or scripts

For Claude Code, one command:

claude mcp add --transport http ace https://ace.authoritas.com/api/mcp --header "Authorization: Bearer <your-api-key>"

For anything else, use the same URL and header. The endpoint speaks MCP streamable HTTP and negotiates the protocol version with your client, currently up to 2025-06-18. Server-sent events are disabled; the server is stateless, so no session store is involved.

Discovery methods (initialize, ping, tools/list) work with no key. Every tools/call requires a valid key. Verify a connection without a client:

curl -X POST https://ace.authoritas.com/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

For transport details, see the MCP documentation.

Controlling which tools are available

In the ACE app, go to Settings, Developer console, MCP.

• Tools tab: turn each tool on or off per project.
• Try it tab: run a tool with custom JSON arguments and see the result, so you can confirm it works before wiring it into your editor.

Two things worth knowing:

1. Discovery always lists the full catalogue. A disabled tool still appears in tools/list; calling it returns an error telling you to enable it. This keeps the advertised catalogue stable for clients that cache it.
2. Scope is checked separately from enablement. A tool can be enabled for your project and still refuse a key that lacks the scope. The error names the scopes that would work.

Tool catalogue

36 tools. On means enabled by default; opt means you enable it under Settings, Developer console, MCP. Tools marked credits consume credits on a live key, or the free monthly quota on a test key.

Documentation

Any valid key can read the docs, whatever its scopes.

Contextual Enrichment Engine

Scope: enrichment:write. See Contextual Enrichment Engine.

Jobs

Scope: enrichment:read, except cancel_job which needs enrichment:write.

Account, feeds, and utilities

Content and media

Webhooks

Scope: webhooks:read to list, webhooks:write to change. All opt-in. See Webhooks.

Google Merchant Center

All opt-in, and all need a connected Merchant Center account. Read tools need enrichment:read; write tools need enrichment:write. Most take an optional connection id and default to the project's first active connection.

The last five mutate a live Merchant Center account. They are marked as destructive in the protocol, so a well-behaved client asks you to confirm before running them. Start with the read tools.

Tool reference

list_docs

Discover which doc pages exist.

{ "name": "list_docs", "arguments": { "prefix": "guides" } }

Returns { "pages": [ { "path": "guides/webhooks", "title": "Webhooks" }, ... ] }.

read_docs

Read one page in full.

{ "name": "read_docs", "arguments": { "path": "contextual-enrichment-engine" } }

generate_contextual_rules

Derive the eight section rules for a product set. Uses credits.

{
  "name": "generate_contextual_rules",
  "arguments": {
    "products": [
      { "id": "sku-1", "title": "Merino base layer", "category": "Outdoor", "brand": "Fjell" }
    ],
    "creativityLevel": 3
  }
}

enrich_content

Generate content types per product, grounded in rules. Uses credits. Returns a job id.

run_enrichment_pipeline

Rules and content in one call. Uses credits. Returns a job id.

{
  "name": "run_enrichment_pipeline",
  "arguments": {
    "products": [{ "id": "sku-1", "title": "Merino base layer" }],
    "contentTypes": ["product-description", "meta-tags"],
    "targetLanguage": "de-DE"
  }
}

list_jobs, get_enrichment_job, get_job_results, cancel_job

A typical flow: run the pipeline, poll get_enrichment_job until status is terminal, then page get_job_results.

enrich_product

Enrich one product. Uses credits.

generate_content

Structured content from a layout template. Uses credits.

layout selects the generator: product-backed layouts produce a listicle or comparison article, while how-to-guide and editorial produce prose. If you pass productIds that do not exist in the project, the call fails rather than inventing placeholder products, so use search_products to find valid ids.

generate_feed

generate_images

Charged per variant.

translate_content

Utilities

All three are unbilled.

Webhooks

Event types: enrichment.job.succeeded, enrichment.job.partial, enrichment.job.failed, article.job.succeeded, article.job.failed.

Authentication and errors

• Authentication: every tools/call to https://ace.authoritas.com/api/mcp must include a valid key as Authorization: Bearer <your-api-key>. Use the same keys as the REST API. See API Keys.
• Scopes: a key without the scope a tool requires gets an error naming the scopes that would work. Widen the key rather than retrying.
• Rate limits: keys have a requests per minute limit. Exceeding it returns a rate limit error. See API Reference.
• Credits: enrichment, content, and image tools consume credits on a live key and the free monthly quota on a test key. Check with get_usage, or GET /api/v1/usage.

Troubleshooting

Tips for daily use

• Ask your assistant to call list_docs and read_docs before it writes integration code, so it works from the current documentation.
• Start with check_agentic_readiness on a sample. It is free and tells you which products are too thin to enrich well.
• Prefer run_enrichment_pipeline for a first run and enrich_content with cached rules for later batches.
• Keep the Merchant Center write tools disabled until you specifically need them.