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

# NoimosAI MCP Server

> Use NoimosAI from Claude, ChatGPT, Cursor, and other MCP-compatible clients.

## Overview

The NoimosAI MCP Server exposes your NoimosAI workspace through the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, MCP-compatible clients can chat with the NoimosAI agent, list workspaces and integrations, and publish social media posts directly from inside the client.

Two ways to connect:

* **Remote MCP (recommended)** — Hosted at `https://mcp.noimosai.com/mcp`. Browser OAuth, no install, runs as you.
* **Local MCP (`@agos-labs/noimosai-mcp`)** — Run the server locally via npm. Suited for headless / API-key flows.

<Tabs>
  <Tab title="Remote (Recommended)">
    Endpoint: `https://mcp.noimosai.com/mcp`

    ### Requirements

    * A NoimosAI account (signed in)
    * A client that supports remote MCP / custom connectors

    ### Authorization

    The client self-registers, then a browser opens for NoimosAI login plus consent for the `mcp:tools` scope. After consent, an access token is issued and tool calls run as you.

    ### Setup

    <Tabs>
      <Tab title="Claude Code">
        ```bash theme={null}
        claude mcp add --scope local --transport http noimos https://mcp.noimosai.com/mcp
        ```

        In a session, run `/mcp`, complete consent in the browser, then return to Claude Code.
      </Tab>

      <Tab title="Claude.ai / Desktop">
        Settings → Connectors → **Add custom connector** → set URL to `https://mcp.noimosai.com/mcp` → sign in and consent in the browser.
      </Tab>

      <Tab title="ChatGPT Web">
        Add a custom MCP connector with URL `https://mcp.noimosai.com/mcp`, then complete consent. ChatGPT does not auto-discover generic `search` / `fetch` tools — call NoimosAI tools by name.
      </Tab>
    </Tabs>

    ### Notes

    * Always call `post` with `dryRun: true` first to inspect the payload. Without `dryRun`, posts publish to the real social account.
    * Disconnect by removing the connector from the client.

    ### Troubleshooting

    * **Browser does not open for consent** — remove the connector and re-add it.
    * **No tools listed** — confirm the `mcp:tools` scope was granted and that the account has at least one workspace.
    * **Token expired** — re-authorize from the client.
  </Tab>

  <Tab title="Local (npm)">
    Published on npm as [`@agos-labs/noimosai-mcp`](https://www.npmjs.com/package/@agos-labs/noimosai-mcp). Runs as a child process of the client.

    ### Requirements

    * Node.js `>= 18`
    * An MCP-compatible client (Claude Desktop, Cursor, VS Code, …)
    * A NoimosAI API key from your team settings

    ### Configuration

    Replace `your-api-key` and `your-workspace-id` with values from your NoimosAI team settings.

    <Tabs>
      <Tab title="Claude Desktop">
        Add to `claude_desktop_config.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="Cursor">
        Add to `.cursor/mcp.json`:

        ```json theme={null}
        {
          "mcpServers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>

      <Tab title="VS Code">
        Add to `.vscode/mcp.json`:

        ```json theme={null}
        {
          "servers": {
            "noimosai": {
              "command": "npx",
              "args": ["-y", "@agos-labs/noimosai-mcp"],
              "env": {
                "NOIMOS_API_KEY": "your-api-key",
                "NOIMOS_WORKSPACE_ID": "your-workspace-id"
              }
            }
          }
        }
        ```
      </Tab>
    </Tabs>

    Restart the client after updating the configuration.

    ### Environment Variables

    | Variable              | Required | Description                                                          |
    | --------------------- | -------- | -------------------------------------------------------------------- |
    | `NOIMOS_API_KEY`      | Yes      | NoimosAI API key (available from the API tab in your team settings). |
    | `NOIMOS_WORKSPACE_ID` | No       | Default workspace ID used when a tool call omits `workspaceId`.      |
  </Tab>
</Tabs>

## Tools

Both transports expose the same tools.

### `chat`

Send a message to the NoimosAI agent. Returns structured NoimosPostJson containing the agent's reply and any extracted social media posts. Supports marketing analysis, social media post creation, SEO analysis, and content generation.

| Parameter     | Type     | Required | Description                                                                                  |
| ------------- | -------- | -------- | -------------------------------------------------------------------------------------------- |
| `prompt`      | `string` | Yes      | The message or instruction to send to the agent.                                             |
| `workspaceId` | `string` | No       | Workspace ID. Falls back to `NOIMOS_WORKSPACE_ID` (local) or the authorized account default. |
| `sessionId`   | `string` | No       | Session ID to continue an existing conversation. A new session is created when omitted.      |

### `list_workspaces`

List available workspaces. Returns workspace IDs and names. No parameters.

### `list_integrations`

List connected integrations (social media accounts) for the workspace. Returns account IDs (`providerAccountId`) that the `post` tool requires for each entry.

### `post`

Publish social media posts. Accepts post data in NoimosPostJson format as returned by `chat`. Each entry must include a `providerAccountId` (get it from `list_integrations`). Always start with `dryRun: true` to inspect the payload before publishing.

| Parameter     | Type      | Required | Description                                                                           |
| ------------- | --------- | -------- | ------------------------------------------------------------------------------------- |
| `posts`       | `array`   | Yes      | Array of posts in NoimosPostJson format. Each entry requires `providerAccountId`.     |
| `schedule`    | `string`  | Yes      | Publish timing. `"now"` for immediate, or `"YYYY-MM-DD HH:MM"` for scheduled.         |
| `workspaceId` | `string`  | No       | Workspace ID. Falls back to the default workspace.                                    |
| `dryRun`      | `boolean` | No       | If `true`, shows what would be sent without actually publishing. Defaults to `false`. |

## Related

* [What Is NoimosAI?](/help-center/getting-started/what-is-noimosai)
* [NoimosAI CLI](/developers/cli/overview)
* [npm package](https://www.npmjs.com/package/@agos-labs/noimosai-mcp)