# Install SosoAPI: packages, clients and remote MCP

Canonical URL: https://sosoapi.ai/docs/installation

Connect your agent to SosoAPI using a local package or hosted MCP. This guide covers installation, connection checks and updates.

## Which npm package should I install?

Install sosoapi for a new setup. The packages @sosoapi/cli, sosoapi-cli and sosoapi-mcp are aliases that install the same exact version of sosoapi. They run the same CLI and MCP tools, so you only need one package.

Local MCP requires Node.js 20 or later and npm/npx. Hosted MCP needs no local package. After installing or connecting, sign in to grant access to your accounts.

npm distributions

| Package | Purpose | Command |

| --- | --- | --- |

| sosoapi | Canonical CLI and MCP server | npx -y sosoapi --help |

| @sosoapi/cli | Exact-version alias of sosoapi | npx -y @sosoapi/cli --help |

| sosoapi-cli | Exact-version alias of sosoapi | npx -y sosoapi-cli --help |

| sosoapi-mcp | Exact-version alias of sosoapi | npx -y sosoapi-mcp --help |

- [sosoapi](https://www.npmjs.com/package/sosoapi)

- [@sosoapi/cli](https://www.npmjs.com/package/@sosoapi/cli)

- [sosoapi-cli](https://www.npmjs.com/package/sosoapi-cli)

- [sosoapi-mcp](https://www.npmjs.com/package/sosoapi-mcp)

## Connect a local MCP client

Use the commands below to add a core-profile connection. If SosoAPI is already connected and working, keep that connection. Running sosoapi without arguments starts the stdio MCP server; it waits for the client on stdin.

For Claude Desktop, Cursor or another stdio client, add the JSON below in its MCP settings. The settings location and approval steps vary by client. Restart or reconnect the client if needed, then check that SosoAPI tools are available in your conversation.

```
claude mcp add sosoapi -e SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

```
codex mcp add sosoapi --env SOSOAPI_TOOL_PROFILE=core -- npx -y sosoapi
```

```
{
  "mcpServers": {
    "sosoapi": {
      "command": "npx",
      "args": [
        "-y",
        "sosoapi"
      ],
      "env": {
        "SOSOAPI_TOOL_PROFILE": "core"
      }
    }
  }
}
```

- [MCP tool reference](https://sosoapi.ai/docs/mcp)

## Connect remote MCP with OAuth

In a client that supports remote MCP, OAuth and dynamic client registration, add the URL below. Sign in through the browser and choose the workspaces and actions you want to allow. You do not need to paste an API key, client ID or client secret. To supply media over HTTP, import a public URL; local file upload requires the local MCP server.

ChatGPT custom apps and Claude remote connectors depend on your plan and the connector settings available in that client. These instructions set up a custom connection; they do not describe an app-directory listing.

```
https://gqeshlawtcexsapabaui.supabase.co/functions/v1/remote-mcp
```

- [Authentication and permissions](https://sosoapi.ai/docs/authentication)

## Verify setup without publishing

Check auth status and sign in if needed. Read workspace context and connected accounts, then confirm that the returned account and workspace are the ones you intended. This verifies access without submitting a post; publishing still depends on that account’s permissions.

You do not need to publish a test post to finish setup. Continue your original task with its existing content. The user completes provider consent and reviews the destination, content and time before any requested write.

```
npx sosoapi auth status
```

```
npx sosoapi api contract --route /identity-api/workspace/list --summary
```

## Update or pin a version

Run npx -y sosoapi@latest --help to fetch the current CLI, then restart your MCP client. If the client has a saved command, put the version you want in its args. Aliases stay tied to their exact sosoapi version; updating a separate global installation will not update them.

If you see a version-skew error, compare the installed contract with the operation you need. Update the package in the command your MCP client actually uses, reconnect and try that operation again. A schema mismatch does not require new credentials or broader access.

```
npx -y sosoapi@latest --help
```

```
npx sosoapi api contract --summary
```

- [Troubleshooting](https://sosoapi.ai/docs/troubleshooting)