Mcp Acedatacloud

AceDataCloudMCP

[PyPI version] [Python 3.10+] [License: MIT] [MCP]

A Model Context Protocol (MCP) server for managing your AceDataCloud account through the platform management API.

Check your balance, look up usage and spend, manage API keys, list services, create and pay recharge orders, manage platform tokens, list models, and use account permissions to edit and publish blogs or announcements — directly from Claude, VS Code, Studio, or any MCP-compatible client.

This is the management / console API (platform.acedata.cloud) — different from the data-generation MCP servers (Suno, Midjourney, …) that call api.acedata.cloud.

Tool Reference

The default curated catalog advertises 359 tools before account-permission filtering, including acedatacloud_get_usage_guide. The complete compatibility registry retains 530 tools. Discovery is grouped by business task, not by one tool per REST endpoint.

Categories

Workspace tools cover delegated editing and site/webhook management. Admin tools require their exact permission grants, not just an admin label.

Account & API keys

Catalog & documentation

Applications & deployments

Usage & billing

Sites & branding

Community & wallet

Content & announcements

Email marketing & analytics

Access control & automation

Payment authorization

Administration & risk

Files & utilities

Calling a write/admin tool without confirm=true returns a redacted dry-run preview and performs no HTTP request.

Check usage and retained request details

Use acedatacloud_list_usage to find API calls, acedatacloud_get_usage(usage_id=...) for a record's details, acedatacloud_usage_summary(days=...) for spend by API, and acedatacloud_export_usage for bounded CSV. Keep query time bounds and day-based lookbacks within the most recent 60 days, the retention window for API usage records and billing summaries. Narrow export filters if the CSV exceeds the MCP's byte limit.

Request and response bodies are retained for only 30 days. Records aged 30–60 days still retain trace, status, time, model, usage and actual charges, but detail metadata no longer includes metadata.request or metadata.response. Missing bodies do not mean the call was free or failed: body expiry does not change charges, usage, model aggregates or effective-result statistics. Save bodies at call time if you need longer retention; a later detail lookup or export cannot recover expired bodies.

Check proxy balances before relying on availability

Use acedatacloud_get_balance for a compact balance summary, then acedatacloud_get_application(application_id=...) for application and service details. For proxy services, paused balance synchronization or a synchronization timeout returns the last saved balance, not proof that the service is currently available. Check service status separately, along with the application's disabled and expired_at fields, even when remaining_amount is positive. Balance URLs, platform-token authentication and response field names are unchanged.

Interpret overdraft status

Read allow_overdraft in acedatacloud_get_balance, acedatacloud_list_applications or acedatacloud_get_application before treating a low or negative balance as a hard stop. It defaults to false and is read-only for customers; creating an application or updating its global-balance policy cannot enable it. Administrators may authorize overdraft for Usage applications: calls continue billing against the application's own balance, negative amounts represent unsettled usage, and top-ups offset that debt without resetting cumulative usage. Disabled/expired applications and credential limits still apply.

An overdraft-enabled application's insufficient balance does not trigger global fallback. Otherwise allow_consume_global controls fallback; any overdraft permission is determined by the global application actually charged. Do not infer overdraft authorization from the balance alone.

Find failed invoices

Use acedatacloud_list_invoices(status="Failed") to find caller-owned invoices whose issuance failed. Read the returned failure_reason before deciding whether to apply again or contact support. Failed is a read filter, not an administrator status-update option.

Bank-transfer payments

For a caller-owned order, first call acedatacloud_get_orders_payment_options(id=...) to read the available transfer routes and amount thresholds. Both personal and business accounts can use BankTransfer without business verification, but domestic CNY and international USD transfers require an order amount of at least USD 300. Use the CNY amount displayed at payment time; availability also depends on collection-channel configuration and package eligibility.

Review the order, amount, and payment route, then call acedatacloud_pay_order(order_id=..., pay_way="BankTransfer", confirm=true) only after confirmation. Bank transfers require the authenticated order owner and are not available anonymously.

Invoice red-flush and reapplication

Call acedatacloud_get_order_invoice(order_id=...) to read the active invoice. An automatic red-flush request leaves the invoice Issued; red_state tracks progress. Submission is not completion: do not apply again while confirmation, red-invoice issuance, or archiving is pending. Only after the red invoice is issued and archived does the original become Voided and the order become eligible for reapplication. Use acedatacloud_list_invoices(order_id=...) for invoice history.

Failed or uncertain red-flush results require finance review and do not release the invoice restriction early. Manually issued invoices must first be voided or red-flushed in the tax/invoicing system, then confirmed by finance on the platform.

Website homepage presentation

For a website section, pass presentation={"open_external": false} to acedatacloud_create_site_home_sections or acedatacloud_update_site_home_sections_id to disable external opening; use true to enable it. Read the current section first and review the write preview before calling again with confirm=true. Website sections still render in an iframe; open_external is not supported for Markdown or HTML sections.

Omitting presentation uses Backend defaults on creation and preserves current options on PATCH. PATCH merges supplied presentation keys, so an empty object does not clear existing options. Read back the section with acedatacloud_get_site_home_sections_id; visible sections also return presentation through acedatacloud_list_site_home_sections_public without account credentials.

Check x402 ACE buyback and burn

When the policy is enabled, eligible Base mainnet Circle USDC and Solana mainnet USDC receipts allocate exactly 3% of the received amount to buying and burning ACE without an extra wallet charge. There is no fixed per-operation or daily USDC buyback cap; available funds, market quotes and chain finality can still affect completion time. Recharge is counted once; later API calls using those Credits are not counted again. Historical discounted orders and old-policy orders are not automatically included.

Call acedatacloud_get_order(order_id=...) and inspect ace_burn. settlement_network and settlement_transaction identify the original payment, while execution_network identifies execution on Solana. Pending or Processing is not proof of a burn; only Completed indicates verified final proof, including public swap_signature and burn_signature transaction identifiers. A Base payment awaiting finality can delay the buyback without blocking already credited Credits. A null ace_burn is not evidence of a completed burn. Wallet/payment signatures and authorization payloads remain confidential.

Diagnose x402 order failures

Read acedatacloud_get_order or acedatacloud_list_orders and inspect metadata.x402.last_error / metadata.x402.errors. They preserve the public code, stage, retryable, charged, and params, with public explanation in reason and event time in timestamp. Re-reading the order preserves specific codes such as insufficient_token_balance (insufficient USDC on the selected network) and invalid_signature rather than replacing them with payment_failed.

Treat charged as three-state: explicit false means rejection before settlement; a missing field means the charge state is unknown, not that no charge occurred. A Failed order cannot be retried in place; resolve the wallet issue and create a new order. For support, share only the order ID and public error code, never full payment signatures, wallet signatures, authorization payloads, or raw facilitator/RPC diagnostics.

Connect to the account MCP

This is the management MCP at https://mcp.acedata.cloud/mcp. It uses a platform token, not the per-service ACEDATACLOUD_API_TOKEN used by generation MCPs. Choose one route:

Hosted OAuth reuses or creates a durable platform token. Review the consent screen for the account capabilities being requested; the account's current backend permissions still govern individual tools, and OAuth consent does not grant administrator access. Sensitive writes require their documented confirmation steps. Platform tokens are returned in full only when created; keep them private. Platform token documentation.

Hosted OAuth clients

• Claude / Claude Desktop chat: Add a remote custom connector in Customize → Connectors → Add custom connector, enter https://mcp.acedata.cloud/mcp, select sign-in, and choose Register automatically if Claude asks how to register its OAuth client. Review consent. The Desktop local JSON file is a separate local-process mechanism. Claude connector guide.
• Claude Code: claude mcp add --transport http --scope user acedatacloud https://mcp.acedata.cloud/mcp, then claude mcp login acedatacloud. Check /mcp. Claude Code guide.
• Cursor: Add https://mcp.acedata.cloud/mcp as a remote MCP server and finish browser sign-in. Personal config is ~/.cursor/mcp.json; project config is <project>/.cursor/mcp.json. Cursor guide.
• VS Code / Copilot: Run MCP: Add Server, select HTTP, enter the URL, finish sign-in, and check MCP: List Servers. The VS Code workspace format is <project>/.vscode/mcp.json; its newer portable format is <project>/.mcp.json. VS Code guide.
• Codex: codex mcp add acedatacloud --url https://mcp.acedata.cloud/mcp, then codex mcp login acedatacloud. User settings live in ~/.codex/config.toml. Official Codex guide.

Cursor URL-only example:

{"mcpServers":{"acedatacloud":{"url":"https://mcp.acedata.cloud/mcp"}}}

VS Code-specific workspace example:

{"servers":{"acedatacloud":{"type":"http","url":"https://mcp.acedata.cloud/mcp"}}}

Explicit platform token

1. Sign in or register at Ace Data Cloud → Account Tokens.
2. Click Create and copy the token with the copy button. It starts with platform-; it is an account-management credential, separate from an application's generation API key.
3. Paste only the token into this account MCP's credential field, or set ACEDATACLOUD_PLATFORM_TOKEN for local stdio. Add Bearer only when configuring an HTTP Authorization header yourself.
4. Keep it private and remove it from Account Tokens to revoke access when no longer needed. For a client that supports hosted OAuth, you can instead use the browser sign-in flow described in this guide.

For Claude Code, the shell expands the token when adding the server, so protect the saved user config:

export ACEDATACLOUD_PLATFORM_TOKEN='YOUR_PLATFORM_TOKEN'claude mcp add --transport http --scope user acedatacloud https://mcp.acedata.cloud/mcp \  --header "Authorization: Bearer $ACEDATACLOUD_PLATFORM_TOKEN"

For a shared Claude Code project config, merge only the variable reference into <project>/.mcp.json; each user sets the environment variable independently:

{  "mcpServers": {    "acedatacloud": {      "type": "http",      "url": "https://mcp.acedata.cloud/mcp",      "headers": {"Authorization": "Bearer ${ACEDATACLOUD_PLATFORM_TOKEN}"}    }  }}

Cursor uses ${env:ACEDATACLOUD_PLATFORM_TOKEN} in ~/.cursor/mcp.json or an uncommitted project config. In VS Code, MCP: Open User Configuration supports a masked ${input:platform-token} value in the headers entry; keep that input in the user/workspace format rather than portable .mcp.json. Cursor config · VS Code config.

Local stdio

python -m pip install mcp-acedatacloudexport ACEDATACLOUD_PLATFORM_TOKEN='YOUR_PLATFORM_TOKEN'mcp-acedatacloud

Claude Desktop's local-process config is opened from its developer settings (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{  "mcpServers": {    "acedatacloud": {      "command": "uvx",      "args": ["mcp-acedatacloud"],      "env": {"ACEDATACLOUD_PLATFORM_TOKEN": "YOUR_PLATFORM_TOKEN"}    }  }}

Keep the user-level file private. uvx requires uv on PATH. This is a local MCP process and is separate from Claude's remote connector.

Verify permissions

A healthy MCP connection and tool list show that the client discovered the server. Start with a read such as acedatacloud_get_user_info or acedatacloud_get_balance to verify your account context. Catalog tools can be public reads; seeing them does not prove your platform token can perform account writes. Follow the confirmation flow for mutations and reread the result. For 401, check the token type or OAuth session; for 403, check the account's actual permission grant. Amounts are in Credits, not USD.

Example prompts

• "Draft a Chinese product blog in Markdown, show it for review, then save it."
• "Save an unpublished video blog using my uploaded HTTPS video URL, then submit it for peer review."
• "Submit blog draft <id> for review, then as a different account approve or reject it with a comment."
• "Publish the peer-approved blog draft <id> from a non-reviewer account."
• "Schedule blog <id> for 2026-10-10T09:00:00+08:00."
• "How many credits do I have left?"
• "What did I spend on Suno in the last 7 days?"
• "List my API keys and show which ones have a spend cap."
• "Create a new API key on application <id> named ci." → previews, then run with confirm.
• "Top up application <id> with package <id> and give me the Stripe pay link."

Configuration

Development

pip install -e ".[dev,test,http]"pytest -m "not integration"      # unit testsruff check .                      # lintmypy core tools                   # type-checkmcp-acedatacloud --transport http --port 8000

Notes

• Amounts (remaining_amount, used_amount, totals) are in Credits, not USD.
• The compatibility tool acedatacloud_get_config returns features and an IP-detected lowercase region (or null when unknown). It does not accept country or region overrides. features overrides remain subject to Backend permissions; a frontend region selection is local display state, not a server-region override.
• For public contact-only Dataset services, acedatacloud_get_pricing returns pricing_mode and any reference_quote from the public service catalog. Keep the quote's currency, amount range, unit and status="reference"; these are indicative quotes, not Credit billing rules or purchasable Usage packages. Contact the platform to confirm the scope and final price. No quote is invented when metadata has none.
• Newly created credential/platform tokens are returned in full only once — store them immediately.
• Credential rotation = delete + recreate (no in-place rotate endpoint).
• Blog drafts default to content_type="article" and require Markdown content. For video posts, set content_type="video" and an uploaded HTTPS video_url; Markdown is optional and can be cleared with content="". Public listing accepts a content_type filter. Video/type changes revoke approval just like source edits; submit the saved version for peer review before publication.
• Blog editorial tools use blog:read, blog:write, and blog:publish permissions. Direct grants and permission groups work without making the account a superuser.
• Blog categories are product-updates, tech-sharing (the draft default), product-recommendations, and industry-insights, or an existing administrator-defined slug. Legacy aliases product, engineering, model-news, and comparison are still accepted and normalized by the Backend.
• Category changes revoke draft approval. The category migration also pauses scheduled posts whose category changed; reread the draft and obtain fresh peer approval before publishing or rescheduling it.
• Blog publication requires a submitted draft approved by a different account with blog:read and blog:publish. Rejection requires a reason; approval may include a comment. The publisher must also differ from the reviewer. Read review_version before review; content edits revoke approval, and withdrawal returns a published post to draft.
• Hosted OAuth resolves the signed-in account's canonical permissions dynamically. The consent page displays the actual scopes; accounts without blog grants receive none. Reconnect OAuth to review newly granted permissions. Existing durable platform tokens follow current account permissions, including revocations, on each request.
• Announcement tools require the corresponding account permission.
• New recharge-card allocations accept only ribbon, blossom, dawn and confetti cover themes; omit theme_id to use the Backend default (ribbon). Creation rejects legacy theme IDs; existing cards retain their original covers.

Management API coverage

The checked-in route ledger in contracts/management_surface.json covers the current Platform management API. Every business operation maps to a native typed tool; callbacks, internal/device protocols, website asset delivery and methods rejected by the backend have explicit exclusion reasons. Existing account tools retain their subject-scoped queries. Administrative tools use the backend's canonical permission names and ownership checks.

Hosted tools/list is filtered using the current platform credential's effective permissions from /platform-tokens/me/. Deploy the Backend subject response and the Auth consent changes before this MCP. File upload inputs and binary outputs are Base64 artifacts bounded to 2 MiB; signed download links are returned directly.

For acedatacloud_create_files, provide filename and content_base64, review the preview, then repeat with confirm=true to upload. The result's file_url is publicly accessible: do not upload confidential material. Backend chooses a unique uploads/<uuid> path and preserves a safe filename extension. Supply content_type matching the actual bytes; if omitted or application/octet-stream, Backend infers it from the filename. Neither the extension nor MIME inference converts the file. The returned mime is the stored MIME type. Reuse the returned file_url for other APIs rather than constructing a URL or treating CDN hosting as a permanent archive. The MCP's 2 MiB limit still applies even though Backend accepts larger files.

Discovery and compatibility

The default ACEDATACLOUD_TOOL_PROFILE=curated advertises task-oriented tools instead of duplicate generated REST aliases, redundant PUT variants and web-client helpers (rendering, read receipts, telemetry and protocol plumbing). It keeps personal-account, site, editorial and administrative business workflows. The usage guide lists only tools visible to the current credential. Each advertised API tool also carries acedatacloud/category and acedatacloud/audience metadata in its MCP _meta field.

Active legacy names, arguments and routes remain callable for existing integrations; hidden aliases are not redirected to another implementation. Retired ACE snapshot operations are removed from both profiles and cannot be called. Set ACEDATACLOUD_TOOL_PROFILE=full explicitly for compatibility discovery or diagnostics. This restores discovery only: permissions, ownership checks, secret redaction and confirm=true requirements still apply.

Cross-account collection tools stay discoverable only with the matching :any permission. Personal-account tools continue to scope queries to the authenticated subject. An unrelated administrative permission never promotes an account query into a cross-account query.

To refresh the generated surface with the Backend runtime and then the MCP runtime:

<backend-python> scripts/export_platform_management.py --backend <PlatformBackend> --output /tmp/platform-routes.jsonpython scripts/compile_platform_management.py --input /tmp/platform-routes.json --backend <PlatformBackend>

Both scripts live at the monorepo root. The exporter uses synthetic configuration and does not read a production .env or execute endpoint handlers.

Documentation

Documentation

License

MIT — see LICENSE.