Local development

Production and local dev use different transport paths because Anthropic’s Connector OAuth runs in the cloud and cannot reach localhost.

Prod vs dev

	Production	Local dev
Claude connection	Native Connector	`mcp-remote` in Claude Desktop config
Bridge URL	`https://agent.artos.sh/mcp`	`https://agent.dev.artos.sh/mcp`
OAuth	Anthropic cloud → public `api.artos.sh`	On your machine → local Caddy/API
OAuth client	Claude’s CIMD (`client_id` = claude.ai URL)	Our CIMD doc via `--static-oauth-client-info`
Callback	Claude hosted callback	`localhost:8898/oauth/callback`

Native Connector cannot hit localhost — use mcp-remote for local stacks.

Key URLs

Thing	Production	Dev
Bridge MCP	`agent.artos.sh/mcp`	`agent.dev.artos.sh/mcp`
API / OAuth AS	`api.artos.sh`	`api.dev.artos.sh`
Consent	`my.artos.sh/oauth/consent`	`my.dev.artos.sh/oauth/consent`
Agent profile	`profile.artos.sh/.well-known/ucp`	same
CIMD client	`profile.artos.sh/well-known/oauth-client.json`	same

The CIMD path uses well-known without the leading dot — that is intentional (a CIMD client_id can be any HTTPS URL), not a typo. See Authentication → CIMD.

mcp-remote example


{
  "mcpServers": {
    "artos": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent.dev.artos.sh/mcp",
        "--static-oauth-client-info",
        "https://profile.artos.sh/well-known/oauth-client.json"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/path/to/mkcert-rootCA.pem"
      }
    }
  }
}

NODE_EXTRA_CA_CERTS is required when the dev bridge uses mkcert TLS.

CIMD redirect URIs

The CIMD oauth-client.json must list http://localhost:8898/oauth/callback (and any other dev callback ports you use).

Cursor

Cursor speaks MCP with the same mcpServers shape as Claude Desktop. Drop this into .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global) and reload:


{
  "mcpServers": {
    "artos": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://agent.dev.artos.sh/mcp",
        "--static-oauth-client-info",
        "https://profile.artos.sh/well-known/oauth-client.json"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "/path/to/mkcert-rootCA.pem"
      }
    }
  }
}

Point production setups at https://agent.artos.sh/mcp and drop NODE_EXTRA_CA_CERTS.

Install the shopping skill

The artos-ucp skill (skills/artos-ucp/ in the docs repo) teaches the agent the Artos-specific flows (Connect vs Build, buyer-account tools, confirm_purchase, the crypto rail). Copy it into your project’s skills directory:


# From a clone of artos-docs, install into <your-project>/skills/artos-ucp
pnpm skills:add /path/to/your-project/skills

Re-running the command overwrites the installed copy in place, so it is safe to script as part of a setup step.

Verify your setup

If you run the bridge yourself, doctor checks the whole chain — config, the AP2 signing key, the optional crypto rail, API reachability, your published agent profile, and the OAuth Authorization Server metadata — before you wire an agent to it:


npx @artos-commerce/ucp-cli doctor --api https://api.dev.artos.sh

It prints one line per check (OK / WARN / FAIL) and exits non-zero if anything is broken, so you can gate a dev script or CI step on it. A WARN on the crypto rail just means AGENT_SUI_PRIVATE_KEY is unset (card-only) — that is fine unless you intend to settle on-chain.

Operator docs

Bridge deployment, env vars, and deep troubleshooting are covered in Troubleshooting and Authentication.