Tovanix
Tovanix

MCP Access

Connect your Tovanix account to any MCP-capable AI client. The endpoint is https://tovanix.com/api/mcp/rpc — stateless Streamable HTTP that accepts POST only.

  • Authentication: Authorization: Bearer <credential>, or the X-MCP-Key header; credentials start with mcp_live_ and are shown once
  • Permissions: every capability is off until you enable it; tools/list returns only enabled ones, named tovanix_ plus the capability name
  • Spending and irreversible tools require a totp_code one-time code and respect per-call and daily caps
  • Source IP allow lists, expiry dates and a default rate limit of 120 calls per minute (up to 600)
  • Three resources (capability catalog, account overview, platform guide) and three prompts (account check-up, spending report, expiry check)
  • Errors: 401 invalid credential, 403 source or account state not allowed, 405 not POST, 413 request too large
  • Creating a credential requires reading and accepting the MCP Access Agreement; content and actions sent in your name are your responsibility
  • Besides spending and irreversible actions, key settings such as callback URLs, public posts and public bucket access also require a one-time code; AI posts, support messages, emails and live Telegram reads have per-account rate limits, repeated posts and support messages are rejected, and support messages are labelled “Sent via AI assistant”

POST /api/mcp/rpc

Three credentials, each with its own job

MCP (Model Context Protocol) lets AI clients such as Claude call your Tovanix account’s capabilities as “tools”. In the console you create an MCP credential for each client and enable, one by one, the capabilities it may use; the client connects to the endpoint with that credential and can then look up data and get things done inside a conversation.

MCP has its own endpoint and credentials, independent of the open API and of console sign-in: deleting an MCP credential never affects the open API integrations you already run, and vice versa.

  • Open API /api/v1/* — API key (X-API-Key / signature) — Programs you write — Whatever the key is set to
  • MCP /api/mcp/rpc — MCP credential (Bearer) — AI clients — Nothing — enabled one by one
  • Console — Sign-in session — You — Everything in your account

Quick start

Any MCP client that supports Streamable HTTP and lets you set request headers can connect. Pick your tool below and copy the matching command or config.

You can also check a credential by calling tools/list with curl: the server is stateless, so no initialize call is needed first.

Only a hash of the credential is stored, so it cannot be recovered — if you lose it, delete it and create a new one. Keep it in your client’s configuration; never put it in a public repository, a screenshot or a chat.

Endpoint and authentication

The “MCP Access” page in the console shows the endpoint for your account, ready to copy.

  • Endpoint — Every request goes to this single URL.
  • Transport — Streamable HTTP, stateless: each request is authenticated on its own, only POST is accepted and no Mcp-Session-Id is issued; GET and DELETE return 405.
  • Authentication — Authorization: Bearer <credential>. If your client only lets you add custom headers and not change Authorization, use X-MCP-Key: <credential> instead.
  • Protocol versions — 2025-06-18 (latest), 2025-03-26 and 2024-11-05, negotiated from the version the client sends in initialize; unsupported versions fall back to the latest.
  • Messages — JSON-RPC 2.0, with a 1 MB limit per request body. Batch requests from older clients may contain at most 32 items.
  • Browser requests — Requests carrying an Origin header from anywhere other than the platform’s own sites are rejected (DNS rebinding protection). Desktop and command-line clients send no Origin and are unaffected.

Credentials and permissions

Credentials start with mcp_live_ and are 73 characters long. Each credential has its own settings below, which you can change in the console at any time; an expired or disabled credential stops working immediately.

Before creating a credential you must read and accept the MCP Access Agreement. It sets out the risks of letting an AI operate your account and who bears them: operations and losses that happen through MCP are your responsibility. No credential can be created while no agreement is published; after an update, new credentials need a fresh acceptance and existing ones keep working.

While an account is restricted, MCP only allows read capabilities; write, spending and irreversible actions are refused with a message pointing the user to the console. If the account is frozen, every request returns 403.

Tools and naming

Tool name = tovanix_ + capability name, with dots replaced by underscores. For example, the capability account.balance.get becomes the tool tovanix_account_balance_get.

tools/list returns only the capabilities enabled for this credential. Each tool’s description explains when to use it, what its parameters mean and what to watch out for, which is how AI clients choose between tools.

Read: read-only. Write: reversible changes, such as editing a note. Spend: takes money from your balance. Irreversible: cannot be undone, such as deleting a key or cancelling a card. Spend and irreversible tools require a one-time code (see the next section). Some reversible changes that you still need to approve on the spot — changing a callback URL, publishing a post, making a bucket public — also require a one-time code; in the console they are tagged “Code required”.

One-time codes

Spend and irreversible tools take an extra totp_code parameter, which must be the current 6-digit code from your authenticator app. The AI cannot obtain this code and will ask you for it when needed. The same applies to tools tagged “Code required”.

  • Each code works only once. A code just used in the console cannot be reused through MCP either.
  • If two-factor authentication is not enabled on the account, these tools are always refused, with a prompt to enable it in the console.
  • The code is checked before anything else, so a wrong code never uses up any of the daily spend allowance.

Spend caps

Every spending call goes through these four steps in order; if any step fails, no money is taken.

confirmed_total_usd

Most spending tools require confirmed_total_usd: the total the AI quoted to you and you agreed to. If the actual price at execution is higher, nothing is executed and the AI tells you the new price.

What happens to the allowance on failure

If a call fails and it is certain nothing was charged, the reserved allowance is returned. If the outcome of the charge cannot be confirmed, the allowance stays reserved so that a charge which may have happened is never dropped from the count. Your bills show what was actually charged.

Rate limits and content sent for you

On top of each credential’s own rate limit, tools that write content for you or make live Telegram requests have per-account limits: they are shared by every credential on the account and reset daily at 00:00 UTC+8. Calls over the limit are refused and the AI is told to stop; community posts and support messages that repeat exactly the same content within 10 minutes are refused too, while emails are de-duplicated by their idempotency key rather than by content. In the console these tools are tagged “Rate-limited”.

Content sent in your name

Once you enable the matching tools, the AI can post and reply in the community, message live support and send email from your SMTP account in your name. That content represents you, and you are responsible for it:

Resources and prompts

Besides tools, the server provides three read-only resources and three prompts that clients can use directly.

  • tovanix://catalog — Capability catalog: every area and capability, and which ones this credential has enabled. The AI reads it when it hits “not authorized” or is asked what it can do.
  • tovanix://account/overview — Account overview: account status, services in use, and this credential’s permissions and daily allowance usage. The balance is shown only if “View account balance” is enabled.
  • tovanix://guide — Platform guide: how amounts and currencies are expressed, order states, and what to confirm before placing an order.
  • account_health — — — Account check-up: balance, subscriptions and expiry across services, unusual orders, and a list of things to deal with.
  • spend_report — days, default 30 — Spending report: recent bills and spending summed by service.
  • renewal_check — within_days, default 14 — Expiry check: services about to expire and their renewal cost — nothing is renewed automatically.

Errors and troubleshooting

Connection and authentication problems are returned as HTTP status codes. Business failures come back as tool results (isError: true) whose text tells the AI what to do next, for example “ask the user for a one-time code” or “insufficient balance — ask the user to top up first”.

Connect Tovanix MCP from each AI tool

Replace <YOUR_MCP_CREDENTIAL> with the MCP credential you created in the console.

  • Claude Code — Run in a terminal
    claude mcp add --scope user --transport http tovanix https://tovanix.com/api/mcp/rpc --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>"
  • Codex — Config file: ~/.codex/config.toml
    [mcp_servers.tovanix]
    url = "https://tovanix.com/api/mcp/rpc"
    bearer_token_env_var = "TOVANIX_MCP_CREDENTIAL"
  • Cursor — Config file: ~/.cursor/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • GitHub Copilot (VS Code) — Config file: .vscode/mcp.json
    {
      "servers": {
        "tovanix": {
          "type": "http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer ${input:tovanix-credential}"
          }
        }
      },
      "inputs": [
        {
          "type": "promptString",
          "id": "tovanix-credential",
          "description": "Tovanix MCP credential",
          "password": true
        }
      ]
    }
  • Gemini CLI — Config file: ~/.gemini/settings.json
    {
      "mcpServers": {
        "tovanix": {
          "httpUrl": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • OpenCode — Config file: ~/.config/opencode/opencode.json
    {
      "$schema": "https://opencode.ai/config.json",
      "mcp": {
        "tovanix": {
          "type": "remote",
          "url": "https://tovanix.com/api/mcp/rpc",
          "enabled": true,
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Qwen Code — Run in a terminal
    qwen mcp add --scope user --transport http tovanix https://tovanix.com/api/mcp/rpc --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>"
  • Kimi Code CLI — Config file: ~/.kimi-code/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • CodeBuddy Code — Run in a terminal
    codebuddy mcp add --scope user --transport http --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>" tovanix https://tovanix.com/api/mcp/rpc
  • Qoder CLI — Config file: ~/.qoder/settings.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "streamable-http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Kiro — Config file: ~/.kiro/settings/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae — Config file: .trae/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae CN — Config file: .trae/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Trae CLI — Config file: trae_cli.yaml
    mcp_servers:
      - name: "tovanix"
        url: "https://tovanix.com/api/mcp/rpc"
        type: "http"
        headers:
          Authorization: "Bearer <YOUR_MCP_CREDENTIAL>"
  • GitHub Copilot CLI — Config file: ~/.copilot/mcp-config.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "http",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          },
          "tools": [
            "*"
          ]
        }
      }
    }
  • Cline — Config file: cline_mcp_settings.json
    {
      "mcpServers": {
        "tovanix": {
          "type": "streamableHttp",
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Kilo Code — Config file: ~/.config/kilo/kilo.jsonc
    {
      "mcp": {
        "tovanix": {
          "type": "remote",
          "url": "https://tovanix.com/api/mcp/rpc",
          "enabled": true,
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Continue — Config file: ~/.continue/config.yaml
    mcpServers:
      - name: tovanix
        type: streamable-http
        url: https://tovanix.com/api/mcp/rpc
        requestOptions:
          headers:
            Authorization: Bearer <YOUR_MCP_CREDENTIAL>
  • Zed — Config file: ~/.config/zed/settings.json
    {
      "context_servers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Junie — Config file: ~/.junie/mcp/mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Amp — Config file: ~/.config/amp/settings.json
    {
      "amp.mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Goose — Config file: ~/.config/goose/config.yaml
    extensions:
      tovanix:
        enabled: true
        type: streamable_http
        name: tovanix
        uri: https://tovanix.com/api/mcp/rpc
        headers:
          Authorization: "Bearer <YOUR_MCP_CREDENTIAL>"
        timeout: 300
  • Augment (Auggie) — Run in a terminal
    auggie mcp add tovanix --transport http --url https://tovanix.com/api/mcp/rpc --header "Authorization:Bearer <YOUR_MCP_CREDENTIAL>"
  • Factory Droid — Run in a terminal
    droid mcp add tovanix https://tovanix.com/api/mcp/rpc --type http --header "Authorization: Bearer <YOUR_MCP_CREDENTIAL>" --no-oauth
  • Crush — Config file: ~/.config/crush/crushrc
    mcp add tovanix --type http --url https://tovanix.com/api/mcp/rpc --header Authorization "Bearer <YOUR_MCP_CREDENTIAL>"
  • Warp — Paste in the app settings
    {
      "tovanix": {
        "url": "https://tovanix.com/api/mcp/rpc",
        "headers": {
          "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
        }
      }
    }
  • Windsurf — Config file: ~/.codeium/windsurf/mcp_config.json
    {
      "mcpServers": {
        "tovanix": {
          "serverUrl": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Claude (web / desktop) — Enter the address in the app and add an Authorization header (Bearer + credential)
    https://tovanix.com/api/mcp/rpc
  • LM Studio — Config file: mcp.json
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }
  • Dify — Enter the address in the app and add an Authorization header (Bearer + credential)
    https://tovanix.com/api/mcp/rpc
  • Coze — Enter the address in the app and add an Authorization header (Bearer + credential)
    https://tovanix.com/api/mcp/rpc
  • n8n — Enter the address in the app and add an Authorization header (Bearer + credential)
    https://tovanix.com/api/mcp/rpc
  • Other MCP clients — Paste in the app settings
    {
      "mcpServers": {
        "tovanix": {
          "url": "https://tovanix.com/api/mcp/rpc",
          "headers": {
            "Authorization": "Bearer <YOUR_MCP_CREDENTIAL>"
          }
        }
      }
    }

Frequently Asked Questions

Why does tools/list return an empty list?

The credential has no capabilities enabled yet. Enable the ones you need under “MCP Access” in the console and reconnect.

Why are spending tools always refused?

Check three things: whether the credential’s spend caps are still the default 0, whether two-factor authentication is on, and whether the daily allowance is used up.

Related pages: Let your AI assistant run your Tovanix account · API Documentation · Developer integration

Loading…