> **Shapeless documentation index**
> Fetch https://shapelessai.com/llms.txt to discover every page before exploring further.
> Every page also answers Markdown: append `.md` to its path, or send `Accept: text/markdown`.

# MCP server

The hosted MCP server at shapelessai.com/mcp, the tools it serves, and how each agent host adds it.

*Verified 2026-09-14. Source: https://shapelessai.com/docs/mcp*

The hosted MCP server is **`https://shapelessai.com/mcp`**. Add that URL to any host that speaks
remote MCP and it opens a Shapeless tab to sign in and allow. OAuth, no API key, revocable by the
human.

It is the same operations as the [API](/docs/api) and the [CLI](/docs/cli), discovered as tools -
so an agent host learns the surface instead of reading this page.

## Add it

| Host | How to add it | Steps with screenshots |
| --- | --- | --- |
| **Claude** | Settings → Connectors → Add custom connector → paste the URL → Connect. | [/connect/claude](https://shapelessai.com/connect/claude) |
| **ChatGPT** | Developer mode on (Settings → Security and login) → chatgpt.com/plugins → + → paste the URL, OAuth. | [/connect/chatgpt](https://shapelessai.com/connect/chatgpt) |
| **Claude Code** | `claude mcp add --transport http --scope user shapeless https://shapelessai.com/mcp`, then /mcp → Authenticate. | [/connect/claude-code](https://shapelessai.com/connect/claude-code) |
| **Cursor** | One-click install link, or add the URL to ~/.cursor/mcp.json → Needs login → sign in. | [/connect/cursor](https://shapelessai.com/connect/cursor) |
| **Codex** | `codex mcp add shapeless --url https://shapelessai.com/mcp`, then `codex mcp login shapeless`. | [/connect/codex](https://shapelessai.com/connect/codex) |
| **VS Code** | One-click install link, or MCP: Add Server → HTTP → paste the URL → start it and sign in. | [/connect/vscode](https://shapelessai.com/connect/vscode) |
| **Gemini CLI** | `gemini mcp add --transport http shapeless https://shapelessai.com/mcp`, then /mcp auth shapeless. | [/connect/gemini-cli](https://shapelessai.com/connect/gemini-cli) |

Any other host that speaks remote MCP takes the same URL: `https://shapelessai.com/mcp`.

Every step above was read from the vendor's own documentation; the dated sources are on
[shapelessai.com/connect](https://shapelessai.com/connect).

## The handshake, for an agent adding it itself

- Transport: streamable HTTP at `https://shapelessai.com/mcp`
- Auth: OAuth 2.1, dynamic client registration, PKCE
- Protected-resource metadata: `https://shapelessai.com/.well-known/oauth-protected-resource/mcp`
- Scopes: `read`, `write`, `publish`, `offline_access`

An unauthenticated call answers `401` with `WWW-Authenticate: Bearer resource_metadata="..."`
pointing at that document. The server is stateless - one server per request, no session id - so
nothing breaks when the next request lands on another instance.

## The tools

Every tool's description names the scope its credential needs. Tools that put content out say so
in capitals and carry a destructive annotation, so a host asks the human first. Read-only tools
are annotated read-only and run freely.

| Tool | Scope | What it does |
| --- | --- | --- |
| `me` | `read` | Who am I, plan, credit balance. Call it first to check the credential. |
| `connections_list` | `read` | The connected accounts and their ids. |
| `platforms_list` | none | Limits, media rules, whether a title is required, first-comment support and the settings schema per platform. Read it before `posts_create`. |
| `posts_create` | `publish` | **PUBLISHES.** Put a post you wrote on one connected account: now, at a time, or in the account's next free queue slot. |
| `posts_list` | `read` | The queue: proposed, scheduled, published. |
| `posts_get` | `read` | One post's live state, what it was made from, how it did. |
| `posts_approve` | `publish` | **PUBLISHES.** Proposals to the schedule. |
| `posts_dismiss` | `write` | Reject proposals. Nothing goes out. |
| `posts_publish` | `publish` | **PUBLISHES.** Push a queued post out now. |
| `jobs_create` | `write` | Start a durable run from a goal. |
| `jobs_list` / `jobs_get` / `jobs_brief` / `jobs_tail` | `read` | Find, read, digest and follow runs. |
| `jobs_continue` | `write` | Another turn on a job - resumes a stuck one. |
| `jobs_stop` | `write` | Stop a running job. |
| `characters_list` | `read` | The actor roster and how each voice was made. |
| `characters_voice` | `write` | Design or clone a voice. **Spends credit.** |
| `brain_tree` / `brain_read` | `read` | Brand Memory's file tree and one file. |
| `brain_write` | `write` | Edit Brand Memory. |
| `assets_list` | `read` | The asset library. |
| `agents_list` | `read` | The standing agents. |
| `agents_save` | `write`, or `publish` when armed to autopublish | Create or edit one. |
| `agents_wake` | `publish` | **PUBLISHES.** Run an agent now. |

`posts_create` is `POST /api/posts` in tool clothing: `connectionId`, `text` (the route's
`postText`), `mediaKeys`, `title` (the route's `documentTitle`; YouTube requires one),
`scheduledAt` **or** `queue: true`, `settings`, `firstComment`. Read `platforms_list` first - it
carries the limits and the `settingsSchema` to fill. On the Free plan the sixth post for one UTC
day answers `402 free_daily_cap`, which names the day and when it resets. See
[Posts](/docs/posts).

Two tools exist only on the local stdio server, because they read your disk: `assets_upload`,
`brain_import`, and the `files` argument on a job message. Run it with `shapeless mcp` - see
[CLI](/docs/cli#the-local-mcp-server).

## Work passes both ways

- **Every job result carries `url`** - `https://shapelessai.com/studio/c/<id>` - the conversation
  the human opens. `jobs_create`, `jobs_list`, `jobs_get` and `agents_wake` all decorate.
- **`jobs_brief`** is the token-compact read before replying: the last 30 messages clipped,
  reasoning and tool-activity dropped, an artifact inventory, post counts per queue status.
  Deterministic, no model in the loop.
- **`jobs_list` pages** 200 at a time with a `nextCursor` the tool takes back as `before`.
- **`jobs_tail`** replays from a cursor and follows live, returning when the run ends, 60 seconds
  pass or 200 events arrive. A run with no stream answers `{live: false}` rather than erroring.

There is one **prompt**, `continue` (argument: `id`), which a host like Claude Code surfaces as a
slash command: it loads that conversation's brief and tells the agent to reply into the same
thread with `jobs_continue`.

## Claude Code plugin

The public repo is also a plugin marketplace. The plugin wires up the hosted server and ships a
skill that teaches Claude the ropes:

```
/plugin marketplace add FirstClassTree/shapelessai
/plugin install shapeless@shapeless
```

Then run `/mcp`, pick shapeless and choose Authenticate.

## Other servers

We keep a measured survey of every MCP server that posts to social networks, ours included, at
[shapelessai.com/best-social-media-mcp-servers](https://shapelessai.com/best-social-media-mcp-servers):
endpoint, auth, which tools publish, networks, and the free tier's honest limit, each read from the
vendor's own page.

## Questions

### Is there a free social media MCP server?

Yes, this one. `https://shapelessai.com/mcp` is on the Free plan: OAuth, no API key, 10 posts a day across nine networks, no card. The same tools run on every paid plan.

### Can Claude post to social media?

Through a server that exposes a publishing tool, yes. Add this server as a custom connector, connect an account under Accounts, and ask. `posts_create` publishes or schedules; it is annotated destructive, so Claude asks you before it runs.

### Does it work in ChatGPT, Cursor and Codex too?

Any MCP host that speaks streamable HTTP with OAuth 2.1 can add it; the host table above lists the ones we have verified step by step. Claude Code also has a plugin, and the `shapelessai` CLI runs the same tools over stdio for hosts that cannot reach a hosted server.

### What happens when the free plan's daily cap is hit?

`posts_create` answers with the `free_daily_cap` error, the limit and the time it resets, so an agent can wait rather than retry blindly. Nothing is dropped silently.