# Run your DM sales agent with MCP

Canonical page: https://www.moshi.ai/mcp

Turn your Instagram ads into shopping conversations.
Create and test Moshi flows, improve product answers, and review results from Claude, ChatGPT, Cursor, or another AI client with Moshi’s hosted MCP server.
Your Moshi ads run in your own Meta ad account. Shoppers message your brand’s own Instagram or Messenger account.

## Instructions for AI agents

Use this guide when a user asks you to work with their Moshi account.
The guide is public. Reading it does not give you access to organization data.

1. Check whether your host already exposes Moshi MCP tools. Use that connection if it has the organization the user requested.
2. If Moshi tools are unavailable, ask the user to add `https://mcp.moshi.ai/mcp` to an MCP client with Streamable HTTP and OAuth support.
3. Have the user complete browser sign-in and select an organization. Let the client manage credentials and protocol negotiation.
4. Discover the tools through the client (`tools/list`). Read the live descriptions and input schemas; use their required inputs when calling tools (`tools/call`).
5. Verify access with the read-only `get_products` tool. Return the actual product list. An empty list is a valid result.
6. Continue with the user’s requested task. Use returned identifiers and results; do not invent products, flow IDs, tool arguments, or completed actions.

If your host cannot connect to remote MCP servers, tell the user and point them to the client setup instructions below.
Never ask the user to paste an OAuth token into chat or a configuration file.

## Choose tools for the task

| User request | Tool sequence |
| --- | --- |
| Find an existing flow | `get_organization_ads`, then `get_flow` for the selected flow. |
| Create an unpublished flow | Read `get_products` and `get_creatives`. Confirm the product and goal, then use `create_ad` with `publishToMeta: false`. |
| Check flow creation | Use `poll_ad_status` with the identifier returned by creation. Report the returned status. |
| Test a flow | Use `launch_simulator`, `send_simulator_message`, and `poll_simulator` for the selected flow. These operate on Simulator state. |
| Update product or policy answers | Read `list_brand_docs` and `get_brand_doc`. Show the proposed change, then call `update_brand_doc` after approval. |
| Review performance | Use `get_ad_performance`, `get_leads`, or `get_revenue_summary` as the request requires. |
| Review open carts | Use `get_open_carts`. |
| Review shopper questions | Use `list_conversations` and `get_conversation_messages`. Include only customer details needed for the task. |

Use only the tools exposed by the current connection. The live tool schemas are authoritative for arguments.
The marketing term "flow" corresponds to tools that can contain `ad` or `campaign` in their names.

Before write calls, explain the requested change and get user approval.
Writes include flow creation, knowledge updates, creative uploads, and Simulator actions.
For `create_ad`, keep `publishToMeta` set to `false` unless the user explicitly confirms Meta creation.
When `publishToMeta` is `true`, the tool creates real Meta objects in a paused state. Report that they are paused.
Check the tool result before reporting success. If creation is still pending, report the pending status rather than a completed flow.
Do not repeat a write after a timeout until you check whether it already completed.

## Connection problems

- Authorization required or `401`: ask the user to reconnect and complete OAuth in their MCP client.
- Missing organization binding: reconnect and choose an organization during consent.
- Membership removed: ask an organization owner to restore access.
- Wrong organization: remove and add the connection again, then select the requested organization during consent.
- Missing tool: refresh tool discovery or reconnect. Do not invent an unavailable tool.
- Tool error: report the error and the step that failed. Do not claim the requested action completed.

## Connect

You need a Moshi account with access to an organization.
Use an AI client that supports remote MCP over HTTP with OAuth.

Server URL: `https://mcp.moshi.ai/mcp`

The server is hosted by Moshi.
Sign in with your Moshi account and select your organization.
OAuth connections do not require an API key.

In Claude, add the server URL as a custom connector.
In ChatGPT, create a custom app in developer mode and choose OAuth.
Availability depends on your ChatGPT plan and workspace settings.

For Claude Code, run:

```sh
claude mcp add --transport http moshi https://mcp.moshi.ai/mcp
```

Then open `/mcp` in Claude Code and authenticate.
The optional Claude plugin adds guided Moshi workflows.

For Cursor, add this to your MCP configuration:

```json
{
  "mcpServers": {
    "moshi": {
      "type": "http",
      "url": "https://mcp.moshi.ai/mcp"
    }
  }
}
```

Complete setup instructions: https://docs.moshi.ai/developer/mcp-quickstart

## Try a read-only request

```text
Use Moshi to list the products in my organization. Do not change any data.
```

## Example requests

- Test a shopper conversation: "Use Moshi to test how my agent answers questions about product fit, shipping, and returns in the Simulator. Summarize the answers."
- Improve your agent’s product answers: "Use Moshi to update my agent’s product answers with this shipping policy. Show me the proposed brand knowledge update before saving it."
- Find what stops shoppers from buying: "Use Moshi to summarize the questions and objections shoppers raise most often in recent conversations. Leave out personal details."
- Review open carts: "Use Moshi to show open carts, their products, and their total value."

## Available tools

| Task | Example tools |
| --- | --- |
| Products and flows | `get_products`, `get_creatives`, `create_ad` |
| Product answers and brand knowledge | `list_brand_docs`, `get_brand_doc`, `update_brand_doc` |
| Simulator | `launch_simulator`, `send_simulator_message`, `poll_simulator` |
| Results and insights | `get_ad_performance`, `get_leads`, `get_revenue_summary` |
| Conversations | `list_conversations`, `get_conversation_messages`, `get_heatscore` |

Full tool reference: https://docs.moshi.ai/developer/tools

## Access and changes

Update the product and policy answers in your brand knowledge, then test shopper questions in the Simulator before launch.

Moshi checks your organization membership on every request.
Removing membership stops access.
Conversation tools can return customer data.

Review write requests in your client before approval.
Write tools can change brand knowledge, flows, Simulator state, or Meta data.
`create_ad` does not publish to Meta by default.
When `publishToMeta` is true, it creates real Meta objects in a paused state.
Require explicit confirmation before that call.

Organization access: https://docs.moshi.ai/developer/organization-scope

## Client guides

- Claude: https://docs.moshi.ai/developer/clients/claude-desktop
- Claude Code: https://docs.moshi.ai/developer/clients/claude-code
- ChatGPT: https://docs.moshi.ai/developer/clients/chatgpt
- Cursor and other clients: https://docs.moshi.ai/developer/clients/other-clients

New to Moshi? Create an account at https://app.moshi.ai or talk to Moshi at https://www.moshi.ai/talk?src=mcp.