{"_id":"@autopayos/mcp-server","name":"@autopayos/mcp-server","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@autopayos/mcp-server","version":"1.1.0","description":"Model Context Protocol (MCP) server exposing AutoPayOS ad-spend governance capabilities as MCP tools","publishConfig":{"access":"public"},"main":"./dist/index.js","types":"./dist/index.d.ts","type":"module","bin":{"autopayos-mcp":"dist/cli.js","autopayos-mcp-server":"dist/cli.js"},"exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./server":{"import":"./dist/server.js","types":"./dist/server.d.ts"}},"scripts":{"build":"tsc","dev":"tsx watch src/cli.ts","start":"node dist/cli.js","clean":"rm -rf dist"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.8"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.9.3","tsx":"^4.7.0"},"keywords":["mcp","model-context-protocol","ai-agents","ad-spend-governance","advertising","google-ads","meta-ads","tiktok-ads","autopayos"],"repository":{"type":"git","url":"git+https://github.com/Nourfarrag1/autopayos.git","directory":"packages/mcp-server"},"license":"UNLICENSED","engines":{"node":">=20.0.0"},"_id":"@autopayos/mcp-server@1.1.0","gitHead":"4cd2121a50c01bc6488c017899f982a6745084bd","bugs":{"url":"https://github.com/Nourfarrag1/autopayos/issues"},"homepage":"https://github.com/Nourfarrag1/autopayos#readme","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-RaWjwZdlYsTlZD/kjrhAJcX3qS77QpARJJuXEsgBDApVGvDwhfwlLUl9GJKWEjZ9dCTc1c5TGM80/rySTvJu5g==","shasum":"971b4b485d02c3c8f34d0d81cfdf4cbd248cb84b","tarball":"https://registry.npmjs.org/@autopayos/mcp-server/-/mcp-server-1.1.0.tgz","fileCount":19,"unpackedSize":238315,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDwl+86AMFh2wyTPAjIPjOLYZfngj6bnd+1bzyr2DLhkwIhANPt3ZNAGvnc06Sy63Fx+1ArZqm2Ooka7EXi0ahl/NG0"}]},"_npmUser":{"name":"nfarrag","email":"n.farrag@autopayos.com"},"directories":{},"maintainers":[{"name":"basharkanan211","email":"b.kanan@autopayos.com"},{"name":"lhanash","email":"L.hanash@autopayos.com"},{"name":"nfarrag","email":"n.farrag@autopayos.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_1.1.0_1783939388254_0.5300554360662522"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-13T10:43:08.132Z","1.1.0":"2026-07-13T10:43:08.385Z","modified":"2026-07-13T10:43:08.599Z"},"maintainers":[{"name":"basharkanan211","email":"b.kanan@autopayos.com"},{"name":"lhanash","email":"L.hanash@autopayos.com"},{"name":"nfarrag","email":"n.farrag@autopayos.com"}],"description":"Model Context Protocol (MCP) server exposing AutoPayOS ad-spend governance capabilities as MCP tools","homepage":"https://github.com/Nourfarrag1/autopayos#readme","keywords":["mcp","model-context-protocol","ai-agents","ad-spend-governance","advertising","google-ads","meta-ads","tiktok-ads","autopayos"],"repository":{"type":"git","url":"git+https://github.com/Nourfarrag1/autopayos.git","directory":"packages/mcp-server"},"bugs":{"url":"https://github.com/Nourfarrag1/autopayos/issues"},"license":"UNLICENSED","readme":"# @autopayos/mcp-server\n\n**Model Context Protocol (MCP) server that exposes AutoPayOS ad-spend governance capabilities as tools for AI agents.**\n\nThis package allows any MCP-compatible AI agent (Claude, GPT, etc.) to discover and use AutoPayOS ad-spend governance APIs as native tools.\n\n> **Package:** `@autopayos/mcp-server` — install via `npx @autopayos/mcp-server`\n\n## Installation\n\n```bash\nnpm install @autopayos/mcp-server\n# or\npnpm add @autopayos/mcp-server\n```\n\n## Quick Start\n\n### Option 1: Command Line\n\n```bash\n# With environment variable\nAUTOPAYOS_API_KEY=ak_live_xxxxx npx @autopayos/mcp-server\n\n# With command line argument\nnpx @autopayos/mcp-server --api-key=ak_live_xxxxx\n\n# With custom base URL (for self-hosted)\nnpx @autopayos/mcp-server --api-key=ak_live_xxxxx --base-url=https://api.yourcompany.com\n\n# Hosted SSE endpoint (recommended — always up to date, no local install):\n# Point your MCP config at https://mcp.autopayos.com/sse with X-API-Key header\n```\n\n### Option 2: MCP Configuration (for Claude Desktop, etc.)\n\nAdd to your MCP configuration file:\n\n```json\n{\n  \"mcpServers\": {\n    \"autopayos\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@autopayos/mcp-server\"],\n      \"env\": {\n        \"AUTOPAYOS_API_KEY\": \"ak_live_xxxxx\"\n      }\n    }\n  }\n}\n```\n\n### Option 3: Programmatic Usage\n\n```typescript\nimport { createServer, AutoPayOSClient } from '@autopayos/mcp-server';\n\n// Create MCP server\nconst server = createServer({\n  apiKey: 'ak_live_xxxxx',\n  serverName: 'my-payment-server',\n  serverVersion: '1.0.0',\n});\n\n// Or use the client directly\nconst client = new AutoPayOSClient({ apiKey: 'ak_live_xxxxx' });\nconst result = await client.listPlatformConnections();\n```\n\n## Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_platform_connections` | List connected ad platforms (Google, Meta, TikTok) |\n| `connect_platform` | Start an OAuth connection to an ad platform |\n| `get_campaigns` | List campaigns on a connected platform |\n| `list_adgroups` | List ad groups / ad sets under a campaign |\n| `get_campaign_performance` | Get campaign performance metrics |\n| `get_ad_compliance` | Read platform disapproval / policy-issue verdicts |\n| `get_agent_reputation` | Get the calling agent's KYA reputation profile |\n| `get_spend_summary` | Get a spend report from a platform |\n| `adjust_campaign_budget` | Adjust a campaign daily budget (policy-checked) |\n| `pause_campaign` / `enable_campaign` | Pause or resume a campaign |\n| `pause_ad` / `enable_ad` | Freeze or resume a single ad |\n| `set_target_cpa` / `set_target_roas` | Set bid targets |\n| `update_bid_amount` / `update_bid_strategy` | Adjust bids (rollback-safe) |\n| `simulate_spend_change` | Dry-run a spend change against policy |\n| `get_action_status` | Poll a pending/approval action for its outcome |\n| `rollback_action` | Reverse an eligible completed bid action |\n| `get_action_evidence` | Fetch the tamper-evident evidence bundle for an action |\n| `get_mandate_constraints` | Get the active spend mandates governing the agent |\n| `preview_spend` | Preview the safety-adjusted effective budget |\n| `get_spend_events` | List recent platform actions with evidence hashes |\n| `request_spend_approval` | Generate a human-approval link for a pending change |\n| Profit Truth tools | Read-only campaign/product profit & COGS ledger |\n\n## Example Agent Conversation\n\n```\nUser: \"Increase the budget on my Summer Sale campaign to £750/day\"\n\nAgent: [uses list_platform_connections + get_campaigns]\n       -> Found \"Summer Sale\" on Google Ads\n\nAgent: [uses get_mandate_constraints]\n       -> Effective daily ceiling: £800/day\n\nAgent: [uses simulate_spend_change]\n       -> Allowed by policy, no violations\n\nAgent: [uses adjust_campaign_budget]\n       -> Budget updated to £750/day, evidence hash recorded\n\nAgent: \"Done — Summer Sale is now at £750/day, within your approved £800 ceiling.\"\n```\n\n## Security\n\n- API keys are used for authentication but **never stored** by the MCP server\n- For sensitive operations, use Task Tokens (ephemeral, task-scoped authorization)\n- All requests respect the agent's policy (spend limits, campaign allowlists)\n- Spend changes over thresholds require human approval via WebAuthn\n\n## Environment Variables\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `AUTOPAYOS_API_KEY` | Agent API key (`ak_live_*` or `ak_test_*`) | Yes |\n| `AUTOPAYOS_BASE_URL` | Custom API base URL | No |\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-37cdb19d7414e07568504453e8719348"}