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

# MCP

> Connect AI tools to Ocoya with the Model Context Protocol.

# Connect AI tools to Ocoya

<a className="ocoya-docs-button" href="https://app.ocoya.com/general/settings/mcp">
  Open MCP settings
</a>

Ocoya MCP lets AI clients work with your Ocoya account through approved, workspace-scoped access. After you connect a client, it can inspect workspaces, list social profiles, draft posts, schedule posts, publish immediately, manage brand kits, and run workflows on your behalf.

Use MCP when you want an assistant such as Claude, Codex, Cursor, VS Code, or another MCP-compatible client to perform Ocoya actions directly instead of giving it API keys or asking it to generate REST calls.

<CardGroup cols={2}>
  <Card title="Workspace-aware" icon="building-2">
    The OAuth approval screen lets you choose which Ocoya workspaces the client can access.
  </Card>

  <Card title="No API keys" icon="key-round">
    MCP uses OAuth. Ocoya API keys are not accepted by the MCP server.
  </Card>

  <Card title="Read and write tools" icon="wrench">
    Clients can discover content, create posts, schedule posts, publish posts, and run workflows.
  </Card>

  <Card title="Structured results" icon="braces">
    Tool responses include JSON-friendly `structuredContent` for clients that can consume it.
  </Card>
</CardGroup>

## Endpoint

```txt theme={null}
https://mcp.ocoya.com
```

The endpoint accepts JSON-RPC 2.0 requests over HTTP `POST`. It supports single requests and JSON-RPC batch requests.

If your environment has not moved to the MCP subdomain yet, use:

```txt theme={null}
https://app.ocoya.com/api/mcp
```

## Authentication

Ocoya MCP uses OAuth. No Ocoya API key is required, and API keys are not accepted by the MCP server.

When a client first uses an Ocoya tool, it opens Ocoya in the browser. The user signs in, reviews the requested permissions, selects allowed workspaces, and approves access. The client receives a short-lived access token and can refresh it according to the OAuth flow.

Approved grants can include these capabilities:

| Capability             | What it allows                                                 |
| ---------------------- | -------------------------------------------------------------- |
| `workspace:read`       | Read approved workspaces and brand kits.                       |
| `social_profiles:read` | Read connected social profiles in approved workspaces.         |
| `posts:read`           | List, inspect, and preview posts.                              |
| `posts:write`          | Create drafts, update posts, schedule posts, and delete posts. |
| `posts:publish`        | Publish posts immediately.                                     |
| `workflows:read`       | List and inspect workflows.                                    |
| `workflows:run`        | Toggle workflows and queue workflow runs.                      |

## Client configuration

<AccordionGroup>
  <Accordion title="Claude Code" icon="terminal">
    ```bash theme={null}
    claude mcp add ocoya --transport http https://mcp.ocoya.com
    ```
  </Accordion>

  <Accordion title="Claude Desktop / Web" icon="sparkles">
    Add a custom connector and paste the MCP URL:

    ```txt theme={null}
    https://mcp.ocoya.com
    ```
  </Accordion>

  <Accordion title="Codex" icon="bot">
    ```toml theme={null}
    [mcp_servers.ocoya]
    url = "https://mcp.ocoya.com"
    ```
  </Accordion>

  <Accordion title="Cursor and JSON-based clients" icon="braces">
    ```json theme={null}
    {
      "mcpServers": {
        "ocoya": {
          "url": "https://mcp.ocoya.com"
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="VS Code" icon="code">
    ```json theme={null}
    {
      "servers": {
        "ocoya": {
          "type": "http",
          "url": "https://mcp.ocoya.com"
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

Client configuration formats differ. If your client asks for a transport, choose HTTP or streamable HTTP and use the endpoint above.

## Typical flow

<Steps>
  <Step title="Add the MCP server">
    Configure your MCP-compatible client with `https://mcp.ocoya.com`.
  </Step>

  <Step title="Approve OAuth access">
    Ocoya opens in the browser. Sign in, review permissions, select the workspaces the client may access, and approve the connection.
  </Step>

  <Step title="Resolve workspace and profile IDs">
    Ask the client to list workspaces and social profiles before creating or scheduling posts.
  </Step>

  <Step title="Ask for the Ocoya action">
    The client can call Ocoya tools to draft, schedule, publish, update, delete, or inspect content.
  </Step>
</Steps>

## Useful prompts

Use natural language. The client decides which MCP tools to call.

```txt theme={null}
List my Ocoya workspaces and show the connected social profiles in the Acme workspace.
```

```txt theme={null}
Create a draft post in Acme with this caption: "Our summer launch is live."
```

```txt theme={null}
Schedule that post for LinkedIn tomorrow at 09:00 in the workspace timezone.
```

```txt theme={null}
Show me workflows in Acme and run the product launch workflow with campaignId set to summer-2026.
```

## Manual protocol check

Most users should let their MCP client handle OAuth and JSON-RPC. For diagnostics, an unauthenticated request should return `401` with a `WWW-Authenticate` header that points to Ocoya OAuth metadata.

```bash theme={null}
curl -i https://mcp.ocoya.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

After OAuth, clients call tools through `tools/call`:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "ocoya_list_workspaces",
    "arguments": {}
  }
}
```

## Troubleshooting

| Issue                      | What to check                                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `401` response             | The client has not completed OAuth, the access token expired, or the client is using an API key instead of OAuth. |
| Workspace not found        | The workspace was not selected during approval, or the client is using an ID from a different Ocoya account.      |
| Social profile rejected    | Use `ocoya_list_social_profiles` for the same workspace and pass one of the returned IDs.                         |
| Invalid schedule           | Use an ISO datetime such as `2026-07-01T09:00:00Z`.                                                               |
| Workflow cannot be toggled | Resolve validation errors in the workflow before enabling or disabling it.                                        |

## Safety

Only approve MCP clients you trust. MCP clients can perform write actions in the workspaces you allow, including creating posts, scheduling posts, publishing posts, deleting posts, toggling workflows, and running workflows.

Review the client action before approving sensitive tasks such as immediate publishing or deletion.

## Next

<Card title="MCP tools" icon="list" href="/mcp/tools">
  Review every Ocoya MCP tool, required argument, and common usage pattern.
</Card>