# StoryOS

> StoryOS is an open-source MCP server for developer tools. MCP server connecting Claude or ChatGPT to a StoryOS workspace of records, tasks. It can run locally on your machine or as a hosted remote server.

- **Kind:** MCP server
- **Pricing:** Open source
- **Starting price:** $29 a month
- **Platforms:** Web, CLI, API, macOS, Windows, Linux, self-hosted
- **Website:** https://storyos.dev
- **Repository:** https://github.com/storyfunnels/storyos/tree/HEAD/packages/mcp
- **MCP Registry name:** dev.storyos/storyos
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-19

## About

The README describes this server as a thin, stateless layer over the same API the StoryOS web app uses, so an AI client reads and writes the same customers, jobs, tasks and invoices a team sees in the browser. Access is through a personal API token scoped to one workspace, and the server exposes read, write, schema-building and automation tools.

Writes made through a connected assistant appear in StoryOS as made by the AI under the connecting person's name, and actions the site marks as gated wait in an inbox for a human to approve. The README also notes that the server can be pointed at a self-hosted instance or the cloud app and offers a hosted Streamable HTTP endpoint for connectors that cannot run a local process.

It suits people who already keep business records in StoryOS and want Claude or ChatGPT to query, update and comment on them. Automation tools are limited to admin-scoped tokens.

## Features

- **Record querying and editing:** Filter, sort, create, update, link and delete records in a StoryOS workspace by field name.
- **Schema-aware writes:** A describe-database tool returns exact field names and types so assistants write against the real schema.
- **Comments and file attachments:** Add comments to records and attach files from a URL or inline base64 content.
- **Workspace building tools:** Create spaces, databases, fields, views and relations for admin-scoped tokens.
- **Automation management:** List, create, update and delete automation rules on a database for admin tokens.
- **Skills as resources and prompts:** Workspace skills are exposed as MCP resources and prompts as well as tools.

## Good for

- Asking an assistant what tasks are overdue across client jobs
- Turning call notes into tasks linked to a specific job
- Drafting client status updates from open work on each record
- Building a new database and views from a plain-language description
- Attaching files or comments to customer records from a chat

## Install

### Claude Code (Terminal)

```sh
claude mcp add --transport http storyos https://mcp.storyos.dev/mcp
```

### Claude Desktop (Settings → Connectors → Add custom connector)

```sh
https://mcp.storyos.dev/mcp
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "storyos": {
      "url": "https://mcp.storyos.dev/mcp"
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "storyos": {
      "type": "http",
      "url": "https://mcp.storyos.dev/mcp"
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "storyos": {
      "serverUrl": "https://mcp.storyos.dev/mcp"
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "storyos": {
      "type": "http",
      "url": "https://mcp.storyos.dev/mcp"
    }
  }
}
```

## Tools

- `get_started`: Orientation and workspace map, with optional reference sections.
- `list_workspaces`: Workspaces the token can access.
- `list_databases`: Databases in a workspace.
- `describe_database`: A database's schema with exact api names, types and options.
- `search`: Full-text record search.
- `query_records`: Filter, sort and paginate records.
- `get_record`: One record in full by uuid or public number.
- `get_links`: Web-app URLs for databases, views and records.
- `create_record`: Create a record with values and relations.
- `update_record`: Merge-update a record.
- `delete_record`: Trash a record, restorable for 30 days.
- `link_records`: Link records through a relation field.
- `unlink_records`: Remove specific links from a relation field.
- `add_comment`: Post a comment on a record.
- `attach_file`: Attach a file to a record from a URL or base64 content.
- `list_attachments`: List a record's files.
- `delete_attachment`: Remove a file from a record.
- `run_button`: Press a button field to run its actions.
- `list_spaces`: List spaces.
- `create_space`: Create a space.
- `create_database`: Create a database.
- `update_database`: Rename or move a database.
- `delete_database`: Delete a database.
- `add_field`: Add a field to a database.
- `update_field`: Update a field.
- `delete_field`: Delete a field.
- `change_field_type`: Convert a field's type.
- `create_view`: Create a view.
- `update_view`: Update a view.
- `delete_view`: Delete a view.
- `create_relation`: Link two databases with a relation.
- `delete_relation`: Remove a relation between databases.
- `reorder_fields`: Set field order.
- `reorder_views`: Set view order.
- `list_skills`: Skills visible to the caller.
- `run_skill`: Resolve a skill's instructions and record the run.
- `list_automations`: Rules on a database with triggers and last-run status.
- `get_automation`: One rule's full editable definition.
- `create_automation`: Create an automation rule.
- `update_automation`: Update an automation rule.
- `delete_automation`: Delete an automation rule.

## FAQ

### How does the server authenticate?

Each user creates a personal API token in StoryOS (prefixed mn_pat_), scoped to one workspace, and sets it as STORYOS_TOKEN. The hosted endpoint takes the token as a Bearer header on each request.

### Which transports are supported?

The package runs over stdio for local clients, and the README describes a stateless Streamable HTTP endpoint at /mcp for hosted use.

### Which tools are only available to admins?

The README says the five automation tools are advertised only to admin-scoped tokens, so read- or write-scoped tokens cannot see or change rules.

### What is the package license?

The README does not state a license for the MCP package itself. The StoryOS pricing page says the product is AGPL-3.0 and can be self-hosted.

### Is StoryOS free?

Yes. StoryOS is open source, so you can use and self-host it for free.

### How do I add StoryOS to Claude Code?

Run this command in your terminal: claude mcp add --transport http storyos https://mcp.storyos.dev/mcp

### What are the best alternatives to StoryOS?

The closest alternatives to StoryOS are TestOrchestrator, AIOS Builder, Toolstile and Falcon Builder.

## Where this comes from

- Description: written from the project's README, the project's website and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [TestOrchestrator](https://ai-powered.com/mcp/testorchestrator): TestOrchestrator is a freemium MCP server for developer tools.
- [AIOS Builder](https://ai-powered.com/mcp/aios-builder): AIOS Builder is an MCP server for developer tools.
- [Toolstile](https://ai-powered.com/mcp/toolstile): Toolstile is a freemium MCP server for developer tools.
- [Falcon Builder](https://ai-powered.com/mcp/falcon-builder): Falcon Builder is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/storyos
