> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.writesonic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup Guide

> Step-by-step instructions for connecting the Writesonic Agents MCP server to your AI assistant.

## Prerequisites

Before connecting, make sure you have:

1. A Writesonic account with **Agents access** (beta, [request it](https://writesonic.com/?demo=open))
2. At least one project in your [Agents workspace](https://agents.writesonic.com)

## Connection Details

Use the same values in any client:

| Field          | Value                                  |
| -------------- | -------------------------------------- |
| Name           | Writesonic Agents                      |
| Description    | Writesonic Agents MCP                  |
| Server URL     | `https://mcp.agent.writesonic.com/mcp` |
| Authentication | OAuth                                  |

## Claude.ai (Web)

1. Go to **Settings** in Claude.ai
2. Navigate to **Connectors** (under **Customize**)
3. Click **Add custom connector**
4. Enter the name `Writesonic Agents` and the server URL `https://mcp.agent.writesonic.com/mcp`
5. Click **Add**, then **Connect**: you'll be redirected to Writesonic to authorize access
6. Sign in and approve the connection
7. You're ready to work with your Agents workspace

<Note>
  On a **Team or Enterprise** plan, only Owners can add custom connectors. See [Organization Setup](#organization-setup) below.
</Note>

## Claude Desktop

Add the following to your `claude_desktop_config.json`:

<CodeGroup>
  ```json macOS theme={"system"}
  // ~/Library/Application Support/Claude/claude_desktop_config.json
  {
    "mcpServers": {
      "writesonic-agents": {
        "url": "https://mcp.agent.writesonic.com/mcp"
      }
    }
  }
  ```

  ```json Windows theme={"system"}
  // %APPDATA%\Claude\claude_desktop_config.json
  {
    "mcpServers": {
      "writesonic-agents": {
        "url": "https://mcp.agent.writesonic.com/mcp"
      }
    }
  }
  ```
</CodeGroup>

Restart Claude Desktop after saving. On first use, you'll be prompted to authenticate with Writesonic.

## Claude Code (CLI)

Run in your terminal:

```bash theme={"system"}
claude mcp add writesonic-agents --transport http https://mcp.agent.writesonic.com/mcp
```

On the first tool call, Claude Code opens a browser window for OAuth authentication.

## ChatGPT

Custom connectors in ChatGPT require **Developer Mode**.

1. Open **Settings › Connectors** (ChatGPT prompts you to enable **Developer Mode** if it isn't already on)
2. Click **Create** to open the new connector dialog
3. Enter:
   * **Name:** `Writesonic Agents`
   * **Description:** `Writesonic Agents MCP`
   * **Server URL:** `https://mcp.agent.writesonic.com/mcp`
   * **Authentication:** OAuth (settings are discovered automatically once a valid URL is entered)
4. Accept the "custom MCP servers introduce risk" notice and click **Create**
5. Click **Connect** and sign in to Writesonic via OAuth

For workspace-wide rollout, see [Organization Setup](#organization-setup).

## Organization Setup

On **Team**, **Enterprise**, and ChatGPT **Business/Enterprise** plans, only Owners and Admins can add custom connectors. Setting one up at the organization level only makes Writesonic Agents **available** to your team, it does not connect anyone automatically.

<Note>
  Each member still connects and authorizes individually, signing in through OAuth with their own Writesonic account, before they can use the tools.
</Note>

### Claude (Owners & Primary Owners)

1. Open **Settings** and go to **Organization settings**
2. In the left sidebar under **Libraries**, select **Connectors**
3. In the top-right, click the **Add** dropdown and choose **Custom**
4. Enter:
   * **Name:** `Writesonic Agents`
   * **Remote MCP server URL:** `https://mcp.agent.writesonic.com/mcp`
5. Leave the **OAuth Client ID** and **OAuth Client Secret** fields (under **Advanced settings**) blank, authorization is handled automatically
6. Click **Add**: Writesonic Agents now appears in your organization's connector list

Each member then enables it under **Settings › Connectors** and clicks **Connect** to authenticate with their own account.

### ChatGPT (Workspace Owners & Admins)

Custom connectors require **Developer Mode**. If it isn't on, ChatGPT prompts you to enable it during this flow.

1. Open the ChatGPT **admin panel** and go to **Apps**
2. Click **Create** (top-right) to open the **New App** dialog
3. Fill in:
   * **Name:** `Writesonic Agents`
   * **Description:** `Writesonic Agents MCP`
   * **Connection:** keep **Server URL** selected and enter `https://mcp.agent.writesonic.com/mcp`
   * **Authentication:** leave as **OAuth**
4. Read the risk notice and tick **"I understand and want to continue"**
5. Click **Create**: the app is created as a draft (shown with a **DEV** label)
6. On the draft, click **Publish**, work through both risk reviews until they show **Reviewed**, then click **Publish** again
7. Writesonic Agents moves into your **Enabled apps** list

Publishing makes it available to everyone in your workspace, but each user still connects and authorizes it individually via OAuth.

## Authentication

The Agents MCP server uses **OAuth 2.0**. When you first connect:

1. Your client redirects you to the Writesonic login page
2. Sign in with your Writesonic credentials
3. Authorize the integration to access your Agents workspace
4. You're redirected back, the session is now active

Sessions persist across conversations. You won't need to re-authenticate unless your token expires.

<Note>
  Prefer static credentials for a backend integration? Use the [Agents REST API](/api-reference/agents/authentication) with an `X-API-Key` header instead of MCP + OAuth.
</Note>

## Verifying the Connection

After setup, try this prompt:

> "List my Writesonic Agents projects"

The assistant should call the `whoami` tool and return your project list. If this works, you're all set.

## FAQ

<AccordionGroup>
  <Accordion title="Do I need a paid plan?">
    You need an account with Agents access, which is in beta and limited to selected enterprise and agency accounts. [Request access](https://writesonic.com/?demo=open) through your account manager.
  </Accordion>

  <Accordion title="What's the difference from the GEO MCP server?">
    The [GEO MCP](/mcp/mcp-server) (`mcp.writesonic.com`) answers questions about your AI-search visibility data. The Agents MCP (`mcp.agent.writesonic.com/mcp`) operates your Agents workspace: tasks, playbooks, grids, knowledge, and content intelligence. You can connect both.
  </Accordion>

  <Accordion title="Does adding the connector for my organization connect everyone automatically?">
    No. Organization setup only makes it *available*. Each member still connects and authorizes individually via OAuth with their own account.
  </Accordion>

  <Accordion title="Authentication failed or redirect loop">
    * Confirm your account has Agents access
    * Disconnect and reconnect the connector
    * Clear browser cookies for writesonic.com and retry
  </Accordion>

  <Accordion title="No projects found">
    Verify you have at least one project in your [Agents workspace](https://agents.writesonic.com). `whoami` returns projects only for your active workspace.
  </Accordion>

  <Accordion title="Tools not appearing">
    * In Claude Desktop, restart the app after editing `claude_desktop_config.json`
    * In Claude Code, run `claude mcp list` to verify the server is registered
  </Accordion>
</AccordionGroup>