What Is MCP? How AI Agents Use OnePush

MCP (Model Context Protocol) is a standard way for AI assistants to call tools on your apps. With OnePush MCP, your assistant can read contacts, check domain DNS, list forms, and draft social posts through https://api.onepush.app/mcp after you approve a dedicated mcp_ key in the browser.

You do not need to run a second server. The MCP endpoint sits on the same API you already use for POST /v1/send and POST /v1/track.

What is Model Context Protocol (MCP)?

Model Context Protocol is an open standard for connecting AI clients to external tools over a shared protocol. Clients speak MCP. Servers expose tools. The assistant picks a tool, sends arguments, and gets structured results back.

USB-C for AI is the usual analogy, and it holds: one plug shape, many devices. Any MCP-compatible client can talk to OnePush the same way it talks to other MCP servers.

Without MCP, you paste API docs into chat and hope the model invents the right curl. With MCP, the tools are registered. The model calls list_contacts or get_domain_dns_records as tools, not as guessed HTTP.

Why email and messaging teams care

Most product teams still open a dashboard to check contacts, fix DNS, or schedule a social post. That works until you are mid-debug and need a contact count, or until an agent is helping you verify SPF before a launch.

MCP puts those jobs next to the work you are already doing. Same project. Same data. Shorter loop.

OnePush also keeps a hard line on keys. Agents without a key only get help and a connect URL. They cannot see your contacts. You approve access on ctl.onepush.app/mcp/connect, copy an mcp_ key once, and paste it into your client. Revoke it later under Settings → MCP without rotating your sk_ / pk_ API keys.

That design matches how people already use dedicated, revocable agent keys: separate from the main secret, easy to kill if a laptop walks away.

How OnePush MCP works

1. Your client connects to https://api.onepush.app/mcp over Streamable HTTP.
2. With no Authorization header, the server exposes onboarding tools only (mcp_help, start_onepush_connect, optional signup/login).
3. You open the approve URL, sign in, pick a project, and Approve.
4. You paste Authorization: Bearer mcp_… into your MCP client.
5. The same session can use project tools: contacts, events, templates, campaigns, forms, domain DNS, billing reads, social drafts.

Legacy sk_ keys still work on MCP if you already ship them. Prefer mcp_ for day-to-day agent access. Public pk_ and enterprise ek_ keys are rejected on MCP on purpose.

Full client setup lives on the MCP Server guide. Example prompts live on MCP use cases.

How to connect in five minutes

Step 1: Approve a key

Open Approve MCP access. Log in or sign up. Pick a project. Hit Approve. Copy the mcp_ string. It is shown once.

Step 2: Add the server in your client

Put this in your MCP config (exact file path depends on the client):

{
  "mcpServers": {
    "onepush": {
      "url": "https://api.onepush.app/mcp",
      "headers": {
        "Authorization": "Bearer mcp_xxxxxxxxxxxx"
      }
    }
  }
}

Replace the placeholder with your real key. Restart or reload MCP if the client asks. If your client uses a different config shape, use the same URL and Bearer header — details are on the MCP Server page.

Step 3: Ask a boring, useful question

Start with something read-only:

• "How many contacts are in this OnePush project?"
• "Is my sending domain verified?"
• "List my forms and submission counts."

If those work, move on to create contact, track event, or draft a social post. For publish, OnePush requires an explicit confirm flag so the model cannot spray posts by accident.

What you can ask an AI to do

Here are jobs that map cleanly to live tools:

Contacts and events — list contacts, create or update a contact, track a signup event, create a tag.

Email building blocks — list automations (actions), templates, and campaigns so the assistant can narrate what is already configured.

Domain — attach a sending domain, fetch SPF/DKIM/MX records, re-check verification after you publish DNS.

Forms — list forms, pull submissions, read metrics.

Social — list connected profiles, create a draft, schedule in UTC, publish only after you confirm.

Billing — read subscription status, list invoices, open a Stripe portal URL. No card charges through the chat.

If you are still on raw HTTP for transactional send, keep using POST /v1/send. MCP complements the REST API; it does not replace every endpoint on day one.

MCP vs copying API keys into chat

Paste sk_ into the chat — the model may call REST with your secret. The secret sits in history, and revoke means rotating everything that uses that key.

Dashboard only — fine for occasional clicks. Slow when you are already mid-debug and do not want to leave your editor.

OnePush MCP + mcp_ key — tools are registered, the key is revocable, and anonymous clients never see project data. Best default for day-to-day agent work.

Also: an agent with no key can still call start_onepush_connect and hand you the approve link. That is the recommended flow we want agents to use.

Common mistakes

• Using pk_ or ek_ on MCP (rejected).
• Forgetting the Bearer prefix in the Authorization header.
• Expecting anonymous MCP to list contacts (it will not).
• Publishing social posts without reading the confirm step.
• Skipping domain verification, then wondering why production email fails — use the DNS tools, then finish SPF/DKIM in your DNS host. Our deliverability guide covers the records.

FAQ

Do I need a separate MCP server process?

No. OnePush MCP runs on https://api.onepush.app/mcp inside the same API service as the REST endpoints. You only configure the client.

Is MCP the same as an API key?

MCP is the protocol. The mcp_ token is how OnePush authenticates a project on that protocol. Think of mcp_ as a dedicated, revocable agent key, not a replacement for every sk_ use in your backend.

Can any AI client use OnePush MCP?

Yes, if the client supports remote MCP (Streamable HTTP) and lets you set a Bearer header or paste an API key. See the MCP Server page for client setup notes.

What should I do if tools return unauthorized?

Regenerate the key under Settings → MCP, update the client header, and retry. Your project sk_ / pk_ stay unchanged.

Does OnePush MCP send email for me today?

MCP focuses on project management tools (contacts, events, templates, campaigns, forms, domain, billing reads, social). Transactional send remains on the REST send API. Use both: agents for ops and inspection, REST for core product sends.

Next steps

1. Approve a key at ctl.onepush.app/mcp/connect
2. Follow client setup on onepush.app/mcp
3. Grab example prompts from MCP use cases
4. Keep REST docs handy in the developer documentation