# Madgicx MCP - Full Documentation

> Complete documentation for Madgicx MCP - manage Facebook advertising through AI assistants using the Model Context Protocol. Source: https://mcp-docs.madgicx.com

---

# Madgicx MCP Documentation

URL: https://mcp-docs.madgicx.com/docs

Madgicx MCP lets you manage your Facebook advertising through AI assistants like Claude and ChatGPT — using plain English. Ask questions about your campaigns, adjust budgets, duplicate ads, pull performance reports, and more, all from a single conversation.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard that gives AI assistants secure, authenticated access to external services. Madgicx runs a remote MCP server that any compatible client can connect to over OAuth 2.0.

This means you can:

- **Read** your account structure — campaigns, ad sets, ads, and creatives
- **Act** on your ads — pause, start, adjust budgets and bids
- **Analyze** performance — pull insights with breakdowns by age, gender, placement, and more
- **Automate** naming and organization — bulk rename, add prefixes, replace text across entities

## Quick Start

1. **Pick a client**

   Madgicx MCP works with **Claude** (Web, Desktop, Mobile, Code) and **ChatGPT** (Web, API).
   It can also be connected to any MCP client that supports remote servers with OAuth authentication.

2. **Add the connector**

   Point your client at the Madgicx MCP server:

   ```
   https://mcp.madgicx.com/mcp
   ```

   Each client has a slightly different setup flow — see the guides below.

3. **Authorize**

   You'll be redirected to Madgicx to log in and select a team. OAuth 2.0 with PKCE keeps your tokens safe — no secrets are stored in the client.

4. **Start asking**

   ```
   Show me my active campaigns and their spend this week
   ```
   ```
   Pause ad set 120211556789
   ```
   ```
   Duplicate campaign "Summer Sale" with prefix "Fall"
   ```

## Supported Clients

- [Claude](https://mcp-docs.madgicx.com/docs/connecting-clients/claude): Web, Desktop, Mobile, and CLI — native MCP support across all Anthropic platforms
- [ChatGPT](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section): Web interface and Responses API — connect via OpenAI's MCP integration

> **Info:** Madgicx MCP is a standard remote MCP server with OAuth 2.0 authentication. Any MCP-compatible client that supports remote servers and OAuth can connect — just point it at `https://mcp.madgicx.com/mcp`.

## Available Tools

| Category | Examples |
|----------|---------|
| [Identity](https://mcp-docs.madgicx.com/docs/tools/whoiam) | Check your connection, team, and token status |
| [Ad Accounts](https://mcp-docs.madgicx.com/docs/tools/ad-accounts) | List accounts, get details, view activity logs |
| [Campaigns](https://mcp-docs.madgicx.com/docs/tools/campaigns) | Start, pause, set budgets, rename |
| [Ad Sets](https://mcp-docs.madgicx.com/docs/tools/adsets) | Start, pause, manage budgets, bids, spending limits, rename |
| [Ads](https://mcp-docs.madgicx.com/docs/tools/ads) | Start, pause, preview, rename |
| [Creatives](https://mcp-docs.madgicx.com/docs/tools/creatives) | Inspect and batch-retrieve creatives |
| [Insights](https://mcp-docs.madgicx.com/docs/tools/insights) | Performance metrics at account, campaign, ad set, and ad level with breakdowns |

See the [Tools](https://mcp-docs.madgicx.com/docs/tools) section for full parameter documentation on every tool.

## Next Steps

- [Connecting Clients](https://mcp-docs.madgicx.com/docs/connecting-clients): Prerequisites and setup guides for Claude and ChatGPT
- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): OAuth 2.0 flow, scopes, and token management
- [Tools Reference](https://mcp-docs.madgicx.com/docs/tools): Full list of tools with parameters and examples

---

# Connecting Clients

URL: https://mcp-docs.madgicx.com/docs/connecting-clients

Madgicx MCP supports multiple AI clients through the Model Context Protocol standard. Choose your preferred platform to get started.

## Prerequisites

Before connecting, make sure you have:

- **Madgicx account** — any active paid plan
- **Facebook Business connected** — at least one Facebook ad account linked in Madgicx
- **Team membership** — you must belong to at least one Madgicx team
- **Network access** — HTTPS connections to `mcp.madgicx.com` and OAuth redirects to/from `madgicx.com`

## Supported Clients

- [Claude](https://mcp-docs.madgicx.com/docs/connecting-clients/claude): Web, Desktop, Mobile, and CLI — native MCP support across all Anthropic platforms
- [ChatGPT](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section): Web interface and Responses API — connect via OpenAI's MCP integration
- [Other Clients](https://mcp-docs.madgicx.com/docs/connecting-clients/other-clients): Any MCP-compatible client with remote server and OAuth 2.0 support

## Client Comparison

| Feature | Claude Web | Claude Desktop | Claude Code | ChatGPT Web | ChatGPT API |
|---------|-----------|---------------|-------------|-------------|-------------|
| Interface | Browser | Desktop App | CLI | Browser | API |
| OAuth Flow | Built-in | Built-in | Browser redirect | Built-in | DCR-based |
| Best For | General users | Desktop users | Developers | General users | Automation |
| Mobile Sync | Yes | — | — | Yes | — |
| Setup Difficulty | Easy | Easy | Medium | Medium | Medium |

## Common Configuration

All clients connect to the same MCP server:

```
https://mcp.madgicx.com/mcp
```

The server handles authentication via OAuth 2.0 with PKCE, team selection during authorization, and automatic token refresh.

## Next Steps

Choose your client guide to get started:

- [Claude Web](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/web): Quickest way to get started
- [Claude Desktop](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/desktop): Native desktop experience
- [Claude Code](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/code): CLI for developers
- [ChatGPT Web](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/web): Connect via chatgpt.com
- [ChatGPT API](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/api): Programmatic integration

---

# Claude

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/claude

Anthropic's Claude has native MCP support across all platforms — web, desktop, mobile, and CLI.

## Platforms

- [Claude Web](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/web): Connect via claude.ai in your browser
- [Claude Desktop](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/desktop): Native desktop app for macOS and Windows
- [Claude Code](https://mcp-docs.madgicx.com/docs/connecting-clients/claude/code): Command-line interface for developers

## Plan Requirements

| Plan | Custom Connectors |
|------|-------------------|
| Free | 1 connector |
| Pro | Multiple connectors |
| Max | Multiple connectors |
| Team | Multiple connectors |
| Enterprise | Multiple connectors |

## Common Configuration

All Claude platforms connect to the same MCP server:

```
https://mcp.madgicx.com/mcp
```

The server handles authentication via OAuth 2.0 with PKCE, team selection during authorization, and automatic token refresh.

## Mobile Support

Claude for iOS and Android supports remote MCP servers. You can use tools, prompts, and resources from servers already configured via claude.ai. New servers cannot be added directly from mobile — configure them on the web first.

---

# Claude Web

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/claude/web

Claude's web interface at [claude.ai](https://claude.ai) supports remote MCP servers natively through Connectors. This is the quickest way to get started with Madgicx MCP.

## Requirements

- A Claude account (Pro, Max, Team, or Enterprise plan for multiple connectors; Free plan supports 1 connector)
- A modern web browser

## Setup Instructions

1. **Open Connector Settings**

   Navigate to [claude.ai/settings/connectors](https://claude.ai/settings/connectors), or click **Settings** in the sidebar and select **Connectors**.

2. **Add Custom Connector**

   Click the **+** button to add a new custom connector. Enter the Madgicx MCP server URL:

   ```
   https://mcp.madgicx.com/mcp
   ```

   Click **Add** to continue.

3. **Authorize with Madgicx**

   A browser window will open for authorization:

   1. **Log in** to your Madgicx account (if not already logged in)
   2. **Select team** — Choose which Madgicx team to connect
   3. **Review permissions** — Review the requested permissions
   4. **Authorize** — Click the "Authorize" button

   After authorization, you'll be redirected back to Claude.

4. **Enable in Conversations**

   The Madgicx connector is now available. To use it in a conversation:

   1. Open a new or existing conversation
   2. Click the **connectors** icon in the input area
   3. Toggle **Madgicx** to enable it

## Using the Connector

Once enabled, simply ask Claude to interact with your Madgicx data:

**Identity:**
```
What Madgicx team am I connected to?
```

**Campaigns:**
```
Show me my active campaigns
```

**Insights:**
```
What's my ad spend this week?
```

Claude will automatically use the appropriate Madgicx MCP tools.

## Mobile Access

Once configured on the web, your Madgicx connector is automatically available in the Claude iOS and Android apps. You can use all tools, prompts, and resources — but new connectors must be added via the web interface first.

## Troubleshooting

**Connector Not Appearing**

- Ensure you completed the authorization flow
- Try refreshing the page
- Check if you've reached your connector limit (Free plan: 1 connector)

**Authorization Failed**

- Verify you have access to at least one Madgicx team
- Clear your browser cookies and try again
- Contact Madgicx support if the issue persists

**Tools Not Working**

- Ensure the connector is toggled on in the conversation
- Check that your Madgicx account has an active Facebook connection
- Try disconnecting and reconnecting the connector

## Next Steps

- [Available Tools](https://mcp-docs.madgicx.com/docs/tools): Learn what you can do with the connector
- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): Understand the security model

---

# Claude Desktop

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/claude/desktop

Claude Desktop provides native support for MCP connectors, making it easy to connect to Madgicx MCP from your desktop.

## Requirements

- Claude Desktop installed
- macOS or Windows
- Anthropic account with Claude access

## Setup Instructions

1. **Open Settings**

   Launch Claude Desktop and click on **Settings** in the left sidebar, or use the keyboard shortcut:
   - **macOS**: `Cmd + ,`
   - **Windows**: `Ctrl + ,`

2. **Navigate to Connectors**

   In the Settings menu, click on **Connectors** in the sidebar.

3. **Add Custom Connector**

   Click the **Add custom connector** button.

4. **Enter MCP Server URL**

   In the dialog that appears, enter the Madgicx MCP server URL:

   ```
   https://mcp.madgicx.com/mcp
   ```

   Click **Add** to continue.

5. **Authorize with Madgicx**

   A browser window will open for authorization:

   1. **Log in** to your Madgicx account (if not already logged in)
   2. **Select team** — Choose which Madgicx team to connect
   3. **Review permissions** — Review the requested permissions
   4. **Authorize** — Click the "Authorize" button

   After authorization, you'll be redirected back to Claude Desktop.

6. **Enable in Conversations**

   The Madgicx connector is now available. To use it in a conversation:

   1. Open a new or existing conversation
   2. Click the **connectors** icon in the input area
   3. Toggle **Madgicx** to enable it

## Using the Connector

Once enabled, you can ask Claude to use Madgicx tools. For example:

```
What Madgicx team am I connected to?
```

Claude will use the `whoiam` tool to retrieve your user and team information.

## Troubleshooting

**Connector Not Appearing**

- Ensure you completed the authorization flow
- Try restarting Claude Desktop
- Check if you've reached your connector limit (Free plan: 1 connector)

**Authorization Failed**

- Verify you have access to at least one Madgicx team
- Clear your browser cookies and try again
- Contact Madgicx support if the issue persists

## Next Steps

- [Available Tools](https://mcp-docs.madgicx.com/docs/tools): Learn what you can do with the connector
- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): Understand the security model

---

# Claude Code

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/claude/code

Claude Code is Anthropic's command-line interface for Claude. It supports MCP connections for integrating external tools and services.

## Requirements

- Claude Code installed
- Node.js 18+
- Terminal access
- Anthropic account with Claude access

## Installation

If you haven't installed Claude Code yet:

```bash
npm install -g @anthropic-ai/claude-code
```

## Setup Instructions

1. **Add the MCP Server**

   Use the `/mcp` command to add the Madgicx connector:

   ```bash
   claude /mcp add madgicx https://mcp.madgicx.com/mcp
   ```

2. **Authorize in Browser**

   A browser window will open for OAuth authorization:

   1. **Log in** to your Madgicx account
   2. **Select team** — Choose which Madgicx team to connect
   3. **Review permissions** — Review the requested permissions
   4. **Authorize** — Click the "Authorize" button

   After authorization, you'll be redirected back and can close the browser.

3. **Verify Connection**

   Verify the connection was successful:

   ```bash
   claude /mcp list
   ```

   You should see `madgicx` in the list of configured MCP servers.

## Using the Connection

Once connected, Claude Code can use Madgicx tools in your conversations. Start a conversation and ask:

```
What Madgicx team am I connected to?
```

## MCP Commands

### List Connections

```bash
claude /mcp list
```

### Remove Connection

```bash
claude /mcp remove madgicx
```

### Update Connection

To update or reconnect:

```bash
claude /mcp remove madgicx
claude /mcp add madgicx https://mcp.madgicx.com/mcp
```

## Troubleshooting

**Connection Fails**

```bash
# Check network connectivity
curl https://mcp.madgicx.com/health

# Remove and re-add the connection
claude /mcp remove madgicx
claude /mcp add madgicx https://mcp.madgicx.com/mcp
```

**Authorization Timeout**

If the browser authorization times out:

1. Ensure your browser can access `madgicx.com`
2. Check for popup blockers
3. Try running the command again

## Next Steps

- [Available Tools](https://mcp-docs.madgicx.com/docs/tools): Learn what tools are available
- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): Understand OAuth flow details

---

# ChatGPT

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section

OpenAI's ChatGPT supports remote MCP servers through Connectors, available in both the web interface and the Responses API.

## Platforms

- [ChatGPT Web](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/web): Connect via chatgpt.com in your browser
- [ChatGPT API](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/api): Programmatic integration via the Responses API

## Plan Requirements

| Plan | MCP Support |
|------|-------------|
| Free | Not available |
| Plus | Available |
| Pro | Available |
| Team | Available |
| Enterprise | Available |
| Education | Available |

## Common Configuration

All ChatGPT platforms connect to the same MCP server:

```
https://mcp.madgicx.com/mcp
```

Authentication is handled via OAuth 2.0. ChatGPT supports Dynamic Client Registration (DCR) for automatic OAuth setup.

## Mobile Access

Connectors configured on the web automatically sync to ChatGPT mobile apps. You can use all connected tools from iOS and Android.

---

# ChatGPT Web

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/web

ChatGPT's web interface supports remote MCP servers through Connectors. You can connect Madgicx MCP directly from chatgpt.com.

## Requirements

- A ChatGPT account (Plus, Pro, Team, Enterprise, or Education plan)
- Developer Mode enabled in settings

## Setup Instructions

1. **Enable Developer Mode**

   Navigate to **Settings** > **Apps & Connectors** > **Advanced settings** and toggle **Developer Mode** on.

   > **Info:** Your organization must permit Developer Mode. Contact your admin if the toggle is unavailable.

2. **Create a Connector**

   Go to **Settings** > **Connectors** > **Create** and fill in:

   - **Connector name**: `Madgicx`
   - **Description**: `Manage Facebook advertising campaigns, ad sets, ads, and view performance insights through your Madgicx account.`
   - **Connector URL**:
   ```
   https://mcp.madgicx.com/mcp
   ```

3. **Verify Connection**

   If successful, you'll see a list of available Madgicx tools. If it fails, verify the URL and ensure your network can reach the server.

4. **Authorize with Madgicx**

   When you first use the connector in a conversation, you'll be prompted to authorize:

   1. **Log in** to your Madgicx account
   2. **Select team** — Choose which Madgicx team to connect
   3. **Review permissions** — Review the requested permissions
   4. **Authorize** — Click the "Authorize" button

5. **Use in Conversations**

   1. Open a new ChatGPT conversation
   2. Click the **+** button near the message composer, then **More**
   3. Select **Madgicx** from available connectors
   4. Ask ChatGPT to use your Madgicx data

## Using the Connector

Once enabled, ask ChatGPT to interact with your Madgicx data:

**Identity:**
```
What Madgicx team am I connected to?
```

**Campaigns:**
```
Show me my active campaigns
```

**Insights:**
```
What's my ad spend this week?
```

> **Info:** ChatGPT displays tool-call payloads for confirmation. Write operations (create, pause, delete) require manual approval unless you enable conversation-wide remembering.

## Refreshing Metadata

If Madgicx adds new tools or updates descriptions, refresh the connector metadata:

1. Go to **Settings** > **Connectors**
2. Select the **Madgicx** connector
3. Click **Refresh**

## Troubleshooting

**Developer Mode Not Available**

Your organization may restrict Developer Mode. Contact your ChatGPT workspace admin to enable it.

**Connection Fails**

- Verify the connector URL is exactly `https://mcp.madgicx.com/mcp`
- Check that your network can reach the server
- Try removing and re-creating the connector

**Authorization Loop**

- Clear browser cookies for `madgicx.com`
- Ensure popup blockers are disabled
- Try a different browser

## Next Steps

- [Available Tools](https://mcp-docs.madgicx.com/docs/tools): Learn what tools are available
- [ChatGPT API](https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/api): Programmatic integration

---

# ChatGPT API

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/chatgpt-section/api

ChatGPT supports MCP through OpenAI's Responses API. This enables programmatic integration with Madgicx MCP for automation and custom applications.

## Requirements

- OpenAI API access
- Valid API key with tool calling permissions
- Python or other HTTP client

## Basic Usage

### Python SDK

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.madgicx.com/mcp"
    }],
    input="What team am I connected to?"
)

print(response.output_text)
```

### With OAuth Configuration

For explicit OAuth configuration:

```python
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_url": "https://mcp.madgicx.com/mcp",
        "authorization": {
            "type": "oauth"
        }
    }],
    input="What team am I connected to?"
)

print(response.output_text)
```

## OAuth Flow

When making the first request:

1. **Dynamic Client Registration** — OpenAI automatically registers as an OAuth client with Madgicx
2. **Authorization Redirect** — User is redirected to Madgicx for login
3. **Team Selection** — User selects their Madgicx team
4. **Token Exchange** — OAuth tokens are exchanged securely
5. **Tool Execution** — The requested tool is executed with the authenticated context

OpenAI handles token refresh automatically.

## Error Handling

```python
from openai import OpenAI, APIError

client = OpenAI()

try:
    response = client.responses.create(
        model="gpt-4o",
        tools=[{
            "type": "mcp",
            "server_url": "https://mcp.madgicx.com/mcp"
        }],
        input="What team am I connected to?"
    )
    print(response.output_text)
except APIError as e:
    if "authorization" in str(e).lower():
        print("Authorization required. User needs to authenticate.")
    else:
        print(f"API error: {e}")
```

## Available Models

| Parameter | Type | Description |
|-----------|------|-------------|
| gpt-4o | string | Full MCP support |
| gpt-4o-mini | string | Full MCP support |
| gpt-4-turbo | string | Full MCP support |
| gpt-3.5-turbo | string | Limited MCP support |

## Troubleshooting

**Authorization Loop**

- Clear browser cookies for `madgicx.com`
- Ensure popup blockers are disabled
- Try a different browser

**Tool Not Found**

- Verify the `server_url` is correct
- Check that `type: "mcp"` is specified in the tools array

## Next Steps

- [Available Tools](https://mcp-docs.madgicx.com/docs/tools): Learn what tools are available
- [API Reference](https://mcp-docs.madgicx.com/docs/api-reference): Explore API endpoints

---

# Other MCP Clients

URL: https://mcp-docs.madgicx.com/docs/connecting-clients/other-clients

Madgicx MCP is a standard remote MCP server with OAuth 2.0 authentication. Any MCP-compatible client that supports remote servers and OAuth can connect — not just Claude and ChatGPT.

## Requirements

> **Warning:** The client must support **remote** MCP servers (not just local/stdio) and **OAuth 2.0** authentication. Clients that only support local tool servers or API-key auth will not work.

## Setup

1. **Find the MCP or connector settings in your client**

2. **Add a new remote server with the URL**

   ```
   https://mcp.madgicx.com/mcp
   ```

3. **Complete the OAuth flow**

   Your client should open a browser window where you log in to Madgicx, select a team, and approve permissions.

4. **Verify the connection**

   Ask your assistant: *"What Madgicx team am I connected to?"* — it should call the `whoiam` tool and return your user and team details.

## Troubleshooting

**Client doesn't show an OAuth prompt**

Your client may not support remote MCP servers with OAuth. Check its documentation for MCP remote server support. Clients that only support local/stdio transports cannot connect to Madgicx MCP.

**Connection times out**

Ensure your network allows HTTPS connections to `mcp.madgicx.com` and OAuth redirects to/from `madgicx.com`.

**Tools not appearing after connection**

Ask the assistant to call the `whoiam` tool directly. If it returns your user info, the connection is working and the client should discover all available tools automatically.

---

# Authentication

URL: https://mcp-docs.madgicx.com/docs/authentication

Madgicx MCP uses OAuth 2.0 with PKCE (Proof Key for Code Exchange) for secure authentication. This ensures your Madgicx account credentials are never shared with AI clients.

## Security Features

### PKCE (Proof Key for Code Exchange)

PKCE protects against authorization code interception attacks:

1. Client generates a random `code_verifier`
2. Client sends a hash (`code_challenge`) with the authorization request
3. During token exchange, client proves possession of the original `code_verifier`

### Token Security

| Token Type | Lifetime | Storage |
|------------|----------|---------|
| Access Token | 1 hour | Memory only |
| Refresh Token | 30 days | Secure credential store |

### Team Isolation

Each authorization is scoped to a single Madgicx team:

- Tokens are valid only for the selected team
- Switching teams requires re-authorization
- Team admins can revoke access at any time

## Token Refresh

Access tokens expire after 1 hour. The refresh process is automatic:

1. AI client detects expired token
2. Client uses refresh token to request new access token
3. MCP server validates and issues new tokens
4. Tool calls continue without user intervention

## Revoking Access

To revoke MCP access:

1. **From AI Client**: Disconnect the MCP connector
2. **Automatic**: After 30 days of inactivity

## Next Steps

- [OAuth Flow](https://mcp-docs.madgicx.com/docs/authentication/oauth-flow) - Detailed flow documentation

---

# OAuth Flow

URL: https://mcp-docs.madgicx.com/docs/authentication/oauth-flow

This page describes the OAuth 2.0 authorization code flow with PKCE used by Madgicx MCP.

## Flow Overview

### Step 1: Client Initialization

The AI client generates PKCE parameters:

```javascript
// Generate code verifier (43-128 characters)
const codeVerifier = generateRandomString(64);

// Create code challenge (SHA-256 hash, base64url encoded)
const codeChallenge = base64url(sha256(codeVerifier));
```

### Step 2: Authorization Request

Client redirects user to the authorization endpoint:

```
https://mcp.madgicx.com/oauth/authorize?
  response_type=code&
  client_id=CLIENT_ID&
  redirect_uri=CALLBACK_URL&
  scope=openid%20profile%20email%20mcp:read%20mcp:write&
  state=RANDOM_STATE&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256
```

### Step 3: User Authentication

User logs in to Madgicx and selects their team:

1. Enter Madgicx credentials (or SSO)
2. Select team from dropdown
3. Review requested permissions
4. Click "Authorize"

### Step 4: Authorization Code

After approval, user is redirected back with an authorization code:

```
CALLBACK_URL?code=AUTH_CODE&state=RANDOM_STATE
```

### Step 5: Token Exchange

Client exchanges the code for tokens:

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=CALLBACK_URL&
client_id=CLIENT_ID&
code_verifier=CODE_VERIFIER
```

### Step 6: Token Response

Server returns access and refresh tokens:

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZn...",
  "scope": "openid profile email mcp:read mcp:write"
}
```

## Team Selection

During authorization, users select which Madgicx team to connect. The selected team is encoded in the issued tokens and cannot be changed without re-authorization.

## Token Refresh

When the access token expires, use the refresh token:

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=CLIENT_ID
```

Each refresh token can only be used once. Store the new refresh token from the response.

## JWT Token Structure

Access tokens are JWTs with the following claims:

```json
{
  "iss": "https://mcp.madgicx.com",
  "sub": "user_123abc",
  "aud": "https://mcp.madgicx.com/mcp",
  "exp": 1704067200,
  "iat": 1704063600,
  "scope": "openid profile email mcp:read mcp:write",
  "team_id": "team_456def"
}
```

## Security Considerations

1. **State Parameter**: Always validate the `state` parameter to prevent CSRF attacks
2. **PKCE**: Use S256 code challenge method (SHA-256)
3. **Token Storage**: Store tokens securely; never expose in URLs or logs
4. **HTTPS**: All OAuth endpoints require HTTPS

## Related

- [API Reference](https://mcp-docs.madgicx.com/docs/api-reference/endpoints) - OAuth endpoints

---

# Available Tools

URL: https://mcp-docs.madgicx.com/docs/tools

Madgicx MCP provides tools that AI assistants can use to manage your Facebook advertising through your Madgicx account.

## Identity

- [whoiam](https://mcp-docs.madgicx.com/docs/tools/whoiam): Retrieve user identity, team info, and Facebook token status

## Ad Accounts

- [Ad Account Tools](https://mcp-docs.madgicx.com/docs/tools/ad-accounts): List accounts, get details, and view activity logs (3 tools)

## Campaigns

- [Campaign Tools](https://mcp-docs.madgicx.com/docs/tools/campaigns): Read, start, pause campaigns, manage budgets and names (11 tools)

## Ad Sets

- [Ad Set Tools](https://mcp-docs.madgicx.com/docs/tools/adsets): Read, start, pause ad sets, manage budgets, bids, spending limits, and names (17 tools)

## Ads

- [Ad Tools](https://mcp-docs.madgicx.com/docs/tools/ads): Read, start, pause, preview ads, and manage names (11 tools)

## Creatives

- [Creative Tools](https://mcp-docs.madgicx.com/docs/tools/creatives): Inspect and batch-retrieve ad creatives (3 tools)

## Insights

- [Insights Tools](https://mcp-docs.madgicx.com/docs/tools/insights): Performance metrics for accounts, campaigns, ad sets, and ads (4 tools)

## How Tools Work

1. **Tool Selection** — The AI identifies which tool can answer your question
2. **Permission Check** — The MCP server verifies you have the required permissions
3. **Execution** — The tool is executed with your authenticated context
4. **Response** — Results are returned to the AI, which formats them for you

## Using Tools

You don't need to know tool names to use them. Simply ask your question naturally:

**Identity:**
```
What team am I connected to?
```
```
What permissions do I have?
```

**Campaigns:**
```
Show me my active campaigns
```
```
Set campaign 120211556789 budget to $50/day
```
```
Pause campaign 120211556789
```

**Ad Management:**
```
List all ads in campaign 120211556789
```
```
Preview ad 120211559999 in mobile feed format
```
```
Show me the creatives for ad 120211559999
```

**Insights:**
```
What's my total ad spend this month?
```
```
Show me campaign performance broken down by age
```
```
What are my top performing ads by ROAS?
```

The AI assistant will select and use the appropriate tool automatically.

## Next Steps

- [Ad Account Tools](https://mcp-docs.madgicx.com/docs/tools/ad-accounts): Start by discovering your accounts
- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): Understand permissions and OAuth

---

# whoiam

URL: https://mcp-docs.madgicx.com/docs/tools/whoiam

The `whoiam` tool retrieves information about the currently authenticated user and their connected Madgicx team.

## Overview

- **Category**: Identity
- **Parameters**: None required
- **Authentication**: OAuth token

## Use Cases

1. **Verify Connection** — Confirm your MCP client is properly connected to Madgicx
2. **Check Permissions** — Review which OAuth scopes have been granted
3. **Facebook Token Status** — Verify your Facebook integration is active

## Response

| Parameter | Type | Description |
|-----------|------|-------------|
| user_id | string | Your unique Madgicx user identifier |
| team_id | string | The connected Madgicx team identifier |
| permissions | string[] | Array of granted OAuth scopes |
| facebook_token | object | Facebook token status information |

### Facebook Token Object

| Parameter | Type | Description |
|-----------|------|-------------|
| status | "active" \| "expiring" \| "expired" | Current token status |
| expires_at | string | ISO 8601 timestamp of token expiration |

## Example Response

```json
{
  "user_id": "user_123abc",
  "team_id": "team_456def",
  "permissions": ["mcp:read", "mcp:write"],
  "facebook_token": {
    "status": "active",
    "expires_at": "2024-12-31T23:59:59Z"
  }
}
```

## Usage Examples

**Natural Language:**

Ask your AI assistant naturally:

```
What Madgicx team am I connected to?
```

```
Show me my user information
```

```
Is my Facebook connection active?
```

**Direct Query:**

The AI will call the tool with:

```json
{
  "tool": "whoiam",
  "arguments": {}
}
```

## Error Handling

**Unauthorized (401)**

```json
{
  "error": "unauthorized",
  "message": "Access token is invalid or expired"
}
```

**Cause**: Your OAuth token has expired or is invalid.

**Solution**: Reconnect the MCP client to obtain a new token.

**Forbidden (403)**

```json
{
  "error": "forbidden",
  "message": "Missing required scope: mcp:read"
}
```

**Cause**: Your authorization doesn't include the required `mcp:read` scope.

**Solution**: Disconnect and reconnect, ensuring you approve all requested permissions.

## Related

- [Authentication](https://mcp-docs.madgicx.com/docs/authentication): OAuth flow details
- [API Reference](https://mcp-docs.madgicx.com/docs/api-reference/endpoints): HTTP endpoints

---

# Ad Account Tools

URL: https://mcp-docs.madgicx.com/docs/tools/ad-accounts

Tools for discovering and inspecting Facebook ad accounts accessible to the authenticated user.

> **Info:** Use `list_ad_accounts` first to discover available accounts. The returned `account_id` values are required by all other tools.

## list_ad_accounts

List all Facebook ad accounts accessible to the authenticated user. Returns each account's ID, name, status, and currency.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| limit | number | Results per page (1-1000, default: 1000) |
| auto_paginate | boolean | Automatically fetch all pages (default: true) |
| next_page_url | string \| undefined | Pagination URL from a previous response |

### Example

**Natural Language:**
```
What ad accounts do I have access to?
```

```
List all my Facebook ad accounts
```

**Direct Query:**
```json
{
  "tool": "list_ad_accounts",
  "arguments": {}
}
```

---

## get_ad_account

Retrieve comprehensive details for a Facebook ad account, including current status, currency, timezone, billing information, spending limits, and business ownership.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

### Example

```
Show me the details of ad account act_123456789
```

---

## get_ad_account_activities

Retrieve the audit log of significant changes made to a Facebook ad account, such as status changes, payment method updates, and account-level budget modifications.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

### Example

```
Show me the activity log for ad account act_123456789
```

## Related

- [Campaign Tools](https://mcp-docs.madgicx.com/docs/tools/campaigns): Manage campaigns in your accounts
- [Account Insights](https://mcp-docs.madgicx.com/docs/tools/insights): View account-level performance metrics

---

# Campaign Tools

URL: https://mcp-docs.madgicx.com/docs/tools/campaigns

Tools for reading, starting, and pausing Facebook advertising campaigns, plus managing budgets and campaign names.

## get_campaign

Retrieve full configuration details for a single Facebook campaign by its ID, including objective, status, spending cap, and bid strategy.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| campaign_id | string | Facebook Campaign ID to retrieve |

### Example

**Natural Language:**
```
Show me the details of campaign 120211556789
```

**Direct Query:**
```json
{
  "tool": "get_campaign",
  "arguments": {
    "account_id": "act_123456789",
    "campaign_id": "120211556789"
  }
}
```

---

## get_campaigns

Retrieve configuration details for up to 50 Facebook campaigns in a single request. More efficient than calling `get_campaign` for each individually.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| campaign_ids | number[] | List of campaign IDs to retrieve (max 50) |
| next_page_url | string \| undefined | Pagination URL from a previous response |

---

## list_campaigns

List all Facebook campaigns in an ad account with optional filtering by status, objective, or date range.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

### Example

**Natural Language:**
```
Show me all my active campaigns
```

```
List campaigns in account act_123456789
```

**Direct Query:**
```json
{
  "tool": "list_campaigns",
  "arguments": {
    "account_id": "act_123456789"
  }
}
```

---

## pause_campaign

Pause a currently active Facebook campaign, stopping delivery of all its ad sets and ads simultaneously. Can be reactivated without recreating the campaign structure.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| object_id | string | Campaign ID to pause |

> **Warning:** Only campaigns with `ACTIVE` status can be paused.

### Example

**Natural Language:**
```
Pause campaign 120211556789
```

**Direct Query:**
```json
{
  "tool": "pause_campaign",
  "arguments": {
    "account_id": "act_123456789",
    "object_id": "120211556789"
  }
}
```

---

## start_campaign

Activate a paused Facebook campaign by setting its delivery status to ACTIVE. Use this to resume delivery without changing the campaign's configuration.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to activate |

> **Warning:** Only campaigns with `PAUSED` status can be started. May fail if the campaign has billing or policy issues.

### Example

```
Start campaign 120211556789
```

---

## set_campaign_budget

Set the budget for a Facebook campaign to a specific amount. Used for Campaign Budget Optimization (CBO) campaigns.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| amount | number | New budget amount in account currency (cents) |

### Example

```
Set campaign 120211556789 budget to $100/day
```

---

## increase_campaign_budget

Increase the budget of a Facebook campaign by a specified amount or percentage.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| amount | number | Amount to increase the budget by |

### Example

```
Increase campaign 120211556789 budget by $20
```

---

## decrease_campaign_budget

Decrease the budget of a Facebook campaign by a specified amount or percentage.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| amount | number | Amount to decrease the budget by |

### Example

```
Decrease campaign 120211556789 budget by $10
```

---

## add_text_to_campaign_name

Add text to a Facebook campaign name by prepending or appending.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| text | string | Text to add (1-100 characters) |
| position | "prefix" \| "suffix" | Where to add text: "prefix" (beginning) or "suffix" (end). Default: "prefix" |
| separator | string \| undefined | Separator between added text and original name (max 5 characters, default: " ") |

### Example

```
Add "[Q1]" prefix to campaign 120211556789 name
```

---

## remove_text_from_campaign_name

Remove specific text from a Facebook campaign name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| text | string | Text to remove (1-100 characters) |
| position | "prefix" \| "suffix" \| "anywhere" | Where to remove text from. Default: "anywhere" |
| case_sensitive | boolean \| undefined | Whether removal is case-sensitive (default: false) |

### Example

```
Remove "[OLD]" from campaign 120211556789 name
```

---

## replace_text_in_campaign_name

Replace one substring with another in a Facebook campaign name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Campaign ID to update |
| text_name_from | string | Text to find and replace (must be non-blank) |
| text_name_to | string | Replacement text (must be non-blank) |

### Example

```
Replace "Summer" with "Winter" in campaign 120211556789 name
```

## Related

- [Ad Set Tools](https://mcp-docs.madgicx.com/docs/tools/adsets): Manage ad sets within campaigns
- [Campaign Insights](https://mcp-docs.madgicx.com/docs/tools/insights): View campaign performance metrics

---

# Ad Set Tools

URL: https://mcp-docs.madgicx.com/docs/tools/adsets

Tools for reading, starting, and pausing Facebook ad sets, plus managing budgets, bids, spending limits, and ad set names. Ad sets control budget, targeting, placement, and delivery optimization for their contained ads.

## get_adset

Retrieve full configuration details for a single Facebook ad set, including audience targeting, budget, bid strategy, optimization goal, and schedule.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| adset_id | string | Facebook Ad Set ID to retrieve |

---

## get_adsets

Retrieve configuration details for up to 50 Facebook ad sets in a single batch request. More efficient than individual requests.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| adset_ids | number[] | List of ad set IDs to retrieve (max 50) |

---

## list_adsets_by_account

List all Facebook ad sets in an ad account with optional filtering by status, date range, or custom conditions.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

### Example

```
Show me all ad sets in account act_123456789
```

---

## list_adsets_by_campaign

List all Facebook ad sets within a specific campaign. Returns targeting, budget, and bidding configuration for each ad set.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| campaign_id | string | Campaign ID to list ad sets for |

### Example

```
Show me all ad sets in campaign 120211556789
```

---

## pause_adset

Pause a currently active Facebook ad set, stopping delivery of all ads within it. The ad set can be reactivated later.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| object_id | string | Ad set ID to pause |

> **Warning:** Only ad sets with `ACTIVE` status can be paused. All ads within the ad set are also paused.

---

## get_adset_activities

Retrieve the audit log of changes made to a Facebook ad set, including budget edits, targeting updates, status changes, and bid modifications. Each entry includes the timestamp and actor who made the change.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| adset_id | string | Ad set ID to retrieve activity log for |

### Example

```
Show me the change history for ad set 120211556789
```

## start_adset

Activate a paused Facebook ad set by setting its delivery status to ACTIVE. All ads within the ad set resume delivery.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to activate |

> **Warning:** Only ad sets with `PAUSED` status can be started. The parent campaign must also be active.

---

## set_adset_budget

Set the budget for a Facebook ad set to a specific amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | New budget amount in account currency (cents) |

### Example

```
Set ad set 120211556789 budget to $50/day
```

---

## increase_adset_budget

Increase the budget of a Facebook ad set by a specified amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | Amount to increase the budget by |

---

## decrease_adset_budget

Decrease the budget of a Facebook ad set by a specified amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | Amount to decrease the budget by |

---

## set_adset_bid

Set the bid amount for a Facebook ad set to a specific value.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | New bid amount in account currency (cents) |

### Example

```
Set ad set 120211556789 bid to $5
```

---

## decrease_adset_bid

Decrease the bid amount of a Facebook ad set by a specified amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | Amount to decrease the bid by |

---

## increase_adset_spending_limit

Increase the spending limit of a Facebook ad set by a specified amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | Amount to increase the spending limit by |

---

## decrease_adset_spending_limit

Decrease the spending limit of a Facebook ad set by a specified amount.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| amount | number | Amount to decrease the spending limit by |

---

## add_text_to_adset_name

Add text to a Facebook ad set name by prepending or appending.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| text | string | Text to add (1-100 characters) |
| position | "prefix" \| "suffix" | Where to add text: "prefix" (beginning) or "suffix" (end). Default: "prefix" |
| separator | string \| undefined | Separator between added text and original name (max 5 characters, default: " ") |

---

## remove_text_from_adset_name

Remove specific text from a Facebook ad set name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| text | string | Text to remove (1-100 characters) |
| position | "prefix" \| "suffix" \| "anywhere" | Where to remove text from. Default: "anywhere" |
| case_sensitive | boolean \| undefined | Whether removal is case-sensitive (default: false) |

---

## replace_text_in_adset_name

Replace one substring with another in a Facebook ad set name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad set ID to update |
| text_name_from | string | Text to find and replace (must be non-blank) |
| text_name_to | string | Replacement text (must be non-blank) |

## Related

- [Campaign Tools](https://mcp-docs.madgicx.com/docs/tools/campaigns): Manage parent campaigns
- [Ad Tools](https://mcp-docs.madgicx.com/docs/tools/ads): Manage ads within ad sets
- [Ad Set Insights](https://mcp-docs.madgicx.com/docs/tools/insights): View ad set performance metrics

---

# Ad Tools

URL: https://mcp-docs.madgicx.com/docs/tools/ads

Tools for reading, starting, pausing, and previewing Facebook ads, plus managing ad names. Ads inherit delivery settings from their parent ad set and contain the creative assets shown to users.

## get_ad

Retrieve full configuration details for a single Facebook ad, including status, creative, and targeting inherited from its parent ad set.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| ad_id | string | Facebook Ad ID to retrieve |

---

## get_ads

Retrieve configuration details for up to 50 Facebook ads in a single request. More efficient than calling `get_ad` individually.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| ad_ids | number[] | List of ad IDs to retrieve (max 50) |

---

## list_ads_by_account

List all Facebook ads in an ad account with optional filtering by effective status, date range, and custom conditions.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

---

## list_ads_by_campaign

List all Facebook ads across all ad sets within a specific campaign. Useful for getting a complete view without querying each ad set separately.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| campaign_id | string | Campaign ID to list ads for |

### Example

```
Show me all ads in campaign 120211556789
```

---

## list_ads_by_adset

List all Facebook ads within a specific ad set. Returns ad configuration data including creative, status, and bidding.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| adset_id | string | Ad set ID to list ads for |

---

## pause_ad

Pause a currently active Facebook ad to stop delivery immediately without deleting it. The ad can be reactivated later.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| object_id | string | Ad ID to pause |

> **Warning:** Only ads with `ACTIVE` status can be paused.

---

## get_ad_preview

Generate a visual HTML preview of a Facebook ad in a specified placement format without delivering it to real users. Useful for verifying creative rendering before launch.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| ad_id | string | Ad ID to preview |
| ad_format | string | Placement format (e.g., DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD) |

### Example

**Natural Language:**
```
Show me a preview of ad 120211556789 in mobile feed format
```

**Direct Query:**
```json
{
  "tool": "get_ad_preview",
  "arguments": {
    "account_id": "act_123456789",
    "ad_id": "120211556789",
    "ad_format": "MOBILE_FEED_STANDARD"
  }
}
```

## start_ad

Activate a paused Facebook ad by setting its delivery status to ACTIVE. The ad resumes serving without changing its creative, budget, or targeting.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad ID to activate |

> **Warning:** Only ads with `PAUSED` status can be started. The parent campaign and ad set must also be active.

---

## add_text_to_ad_name

Add text to a Facebook ad name by prepending or appending. Does not modify budget, status, targeting, or creatives.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad ID to update |
| text | string | Text to add (1-100 characters) |
| position | "prefix" \| "suffix" | Where to add text: "prefix" (beginning) or "suffix" (end). Default: "prefix" |
| separator | string \| undefined | Separator between added text and original name (max 5 characters, default: " ") |

---

## remove_text_from_ad_name

Remove specific text from a Facebook ad name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad ID to update |
| text | string | Text to remove (1-100 characters) |
| position | "prefix" \| "suffix" \| "anywhere" | Where to remove text from. Default: "anywhere" |
| case_sensitive | boolean \| undefined | Whether removal is case-sensitive (default: false) |

---

## replace_text_in_ad_name

Replace one substring with another in a Facebook ad name.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| entity_id | string | Ad ID to update |
| text_name_from | string | Text to find and replace (must be non-blank) |
| text_name_to | string | Replacement text (must be non-blank) |

### Example

```
Replace "v1" with "v2" in ad 120211556789 name
```

## Related

- [Ad Set Tools](https://mcp-docs.madgicx.com/docs/tools/adsets): Manage parent ad sets
- [Creative Tools](https://mcp-docs.madgicx.com/docs/tools/creatives): Create and manage ad creatives
- [Ad Insights](https://mcp-docs.madgicx.com/docs/tools/insights): View ad performance metrics

---

# Creative Tools

URL: https://mcp-docs.madgicx.com/docs/tools/creatives

Tools for inspecting Facebook ad creatives. Creatives define the visual and copy elements of ads, including images, videos, headlines, body text, and call-to-action buttons.

## get_creative

Retrieve full configuration details for a single Facebook ad creative, including all media assets, text elements, call-to-action, and tracking parameters.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| creative_id | string | Facebook Ad Creative ID to retrieve |

---

## get_creatives

Retrieve configuration details for up to 50 Facebook ad creatives in a single batch request. More efficient than individual requests.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| creative_ids | string[] | List of creative IDs to retrieve (max 50) |

---

## list_creatives_by_ad

Retrieve all ad creatives associated with a specific Facebook ad. An ad can have one or more creatives in some formats (e.g., dynamic creative).

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |
| ad_id | string | Ad ID to list creatives for |

### Example

```
Show me the creatives used by ad 120211556789
```

## Related

- [Ad Tools](https://mcp-docs.madgicx.com/docs/tools/ads): Create ads using creatives
- [Ad Preview](https://mcp-docs.madgicx.com/docs/tools/ads#get_ad_preview): Preview how creatives render

---

# Insights Tools

URL: https://mcp-docs.madgicx.com/docs/tools/insights

Tools for retrieving performance metrics across campaigns, ad sets, ads, and ad accounts. Insights include spend, ROAS, reach, impressions, conversions, and more.

## Common Parameters

All insights tools share these parameters for controlling what data is returned:

| Parameter | Type | Description |
|-----------|------|-------------|
| fields | string[] | Metrics to retrieve (default: ["impressions", "spend"]). Examples: impressions, spend, reach, clicks, ctr, cpm, cpp, actions, conversions, purchase_roas |
| time_range | object \| undefined | Custom date range: { since: "YYYY-MM-DD", until: "YYYY-MM-DD" } |
| time_increment | string \| number | Time granularity: "all_days" (default), "monthly", or 1-90 for N-day periods |
| level | string | Aggregation level: "account", "campaign", "adset", or "ad" |
| breakdowns | string[] \| undefined | Segmentation dimensions (e.g., age, gender, placement, country) |
| action_attribution_windows | string[] \| undefined | Attribution windows (e.g., "7d_click", "1d_view") |
| action_breakdowns | string[] \| undefined | Breakdown dimensions for actions |

---

## get_campaign_insights

Retrieve aggregated performance metrics for a Facebook campaign, combining data from all its ad sets and ads.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| campaign_id | string | Campaign ID to retrieve insights for |

Plus all [common parameters](#common-parameters) above.

### Example

**Natural Language:**
```
How did campaign 120211556789 perform last week?
```

```
Show me spend and ROAS for my Summer Sale campaign
```

**Direct Query:**
```json
{
  "tool": "get_campaign_insights",
  "arguments": {
    "campaign_id": "120211556789",
    "fields": ["spend", "impressions", "purchase_roas", "actions"],
    "time_range": {
      "since": "2025-01-01",
      "until": "2025-01-07"
    }
  }
}
```

---

## get_adset_insights

Retrieve performance metrics for a specific Facebook ad set. Aggregates data from all ads within the ad set.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| adset_id | string | Ad set ID to retrieve insights for |

Plus all [common parameters](#common-parameters) above.

### Example

```
Show me the performance of ad set 120211556789 broken down by age and gender
```

---

## get_ad_insights

Retrieve performance metrics for a specific Facebook ad, including spend, impressions, clicks, CTR, CPM, and ROAS. Supports breakdown dimensions and custom date ranges.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| ad_id | string | Ad ID to retrieve insights for |

Plus all [common parameters](#common-parameters) above.

### Example

```
What's the CTR and CPC for ad 120211556789 this month?
```

---

## get_ad_account_insights

Retrieve aggregated performance metrics across all campaigns for a Facebook ad account. Supports level parameter for granular breakdown.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| account_id | string | Facebook Ad Account ID (e.g., act_123456789) |

Plus all [common parameters](#common-parameters) above.

### Example

**Natural Language:**
```
What's my total ad spend this month?
```

```
Show me account-level performance broken down by campaign
```

**Direct Query:**
```json
{
  "tool": "get_ad_account_insights",
  "arguments": {
    "account_id": "act_123456789",
    "fields": ["spend", "impressions", "reach", "purchase_roas"],
    "time_range": {
      "since": "2025-01-01",
      "until": "2025-01-31"
    },
    "level": "campaign"
  }
}
```

## Related

- [Campaign Tools](https://mcp-docs.madgicx.com/docs/tools/campaigns): Manage campaign configuration
- [Ad Account Tools](https://mcp-docs.madgicx.com/docs/tools/ad-accounts): Discover and inspect accounts

---

# API Reference

URL: https://mcp-docs.madgicx.com/docs/api-reference

The Madgicx MCP server exposes several HTTP endpoints for MCP protocol communication and OAuth authentication.

## Base URL

```
https://mcp.madgicx.com
```

## Endpoints Overview

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/mcp` | POST | MCP protocol endpoint |
| `/.well-known/oauth-protected-resource` | GET | OAuth resource metadata |

## Authentication

Most endpoints require Bearer token authentication:

```http
Authorization: Bearer <access_token>
```

Tokens are obtained through the OAuth flow.

## MCP Protocol

The `/mcp` endpoint implements the Model Context Protocol over HTTP transport:

### Request Format

```http
POST /mcp
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "whoiam"
  },
  "id": 1
}
```

### Response Format

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "result": {
    "content": [{
      "type": "text",
      "text": "{...}"
    }]
  },
  "id": 1
}
```

## Rate Limits

| Tier | Requests/minute | Requests/hour |
|------|-----------------|---------------|
| Standard | 60 | 1000 |
| Enterprise | 300 | 5000 |

## Next Steps

- [Endpoints](https://mcp-docs.madgicx.com/docs/api-reference/endpoints) - Detailed endpoint documentation
- [Tools](https://mcp-docs.madgicx.com/docs/tools) - Available MCP tools

---

# Endpoints

URL: https://mcp-docs.madgicx.com/docs/api-reference/endpoints

Detailed documentation for all Madgicx MCP server endpoints.

## MCP Protocol Endpoint

### `POST /mcp`

The main MCP protocol endpoint. Accepts JSON-RPC 2.0 requests.

**Authentication**: Required (Bearer token)

#### Initialize Connection

```http
POST /mcp
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}
```

#### List Tools

```http
POST /mcp

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}
```

#### Call Tool

```http
POST /mcp

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "whoiam"
  },
  "id": 3
}
```

## OAuth Metadata

### `GET /.well-known/oauth-protected-resource`

Returns OAuth 2.0 Protected Resource Metadata.

```json
{
  "resource": "https://mcp.madgicx.com/mcp",
  "authorization_servers": ["https://mcp.madgicx.com"],
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "mcp:read",
    "mcp:write"
  ]
}
```

## OAuth Endpoints

### `GET /oauth/authorize`

Authorization endpoint for OAuth 2.0 flow.

**Parameters**:

| Parameter | Required | Description |
|-----------|----------|-------------|
| `response_type` | Yes | Must be `code` |
| `client_id` | Yes | Client identifier |
| `redirect_uri` | Yes | Callback URL |
| `scope` | Yes | Requested scopes |
| `state` | Yes | CSRF protection |
| `code_challenge` | Yes | PKCE challenge |
| `code_challenge_method` | Yes | Must be `S256` |

### `POST /oauth/token`

Token endpoint for exchanging codes and refreshing tokens.

#### Authorization Code Exchange

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTH_CODE&
redirect_uri=https://example.com/callback&
client_id=client_123&
code_verifier=CODE_VERIFIER
```

#### Token Refresh

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=REFRESH_TOKEN&
client_id=client_123
```

## Error Responses

### HTTP Errors

| Status | Description |
|--------|-------------|
| `400` | Bad Request - Invalid JSON or missing parameters |
| `401` | Unauthorized - Invalid or missing token |
| `403` | Forbidden - Insufficient permissions |
| `404` | Not Found - Unknown method or tool |
| `429` | Too Many Requests - Rate limited |
| `500` | Internal Server Error |

## Related

- [Authentication](https://mcp-docs.madgicx.com/docs/authentication) - OAuth flow details
- [Tools](https://mcp-docs.madgicx.com/docs/tools) - Available MCP tools