No results found. Try a different search term.

Developer Portal

Build on tchop

Integrate tchop into your AI workflows with the MCP Server, or call the GraphQL API directly.

GraphQL API — Stable MCP Server — Beta

Two ways to build

One set of credentials, two access paths, full feature coverage. Both paths use the same authentication headers, same operations, and the same permission model.

🤖

MCP Server

Install the tchop MCP and call operations as natural-language tools from Claude, Cursor, or any MCP-compatible AI assistant. No code required.

Install MCP →

⚡

GraphQL API

POST GraphQL queries directly to your org's endpoint. Full schema access, precise field selection, and tight integration into any codebase.

GraphQL quickstart →

Same foundation: Both paths use identical authentication. Each operation in the API Reference shows both MCP and GraphQL usage.

Get Started

Authentication

Every API request — MCP or GraphQL — requires three authentication headers.

Get your credentials

To get started with the tchop API, contact our support team:
📧 support@tchop.io

Our team will provide you with:

x-tchop-webapp-organisation — your org subdomain
x-tchop-auth-token — your authentication token
x-tchop-api-client-id — your API client ID

Once you have these, you're ready to use both the MCP Server and GraphQL API.

Required headers

x-tchop-webapp-organisationStringYour org subdomain REQUIRED

x-tchop-auth-tokenStringYour authentication token. All permissions derive from this token's role. REQUIRED

x-tchop-api-client-idStringAPI client ID paired with your auth token REQUIRED

Security: Treat the auth token like a password. Never commit it to a repo, paste it in Slack, or include it in screenshots.

Get Started

MCP Server

Install the tchop MCP server and call any operation from an AI assistant using natural language.

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools and APIs safely and reliably. The tchop MCP server wraps the GraphQL API and exposes every operation as a named, typed tool. Your AI assistant can discover tools automatically, call them with validated inputs, receive structured responses, and chain operations together — all without writing any code.

Compatible clients: Claude Desktop, Claude Code, Cursor, Windsurf, and any other assistant that supports MCP over stdio.

Prerequisites

Node.js 20 or later (node --version to check)
tchop API credentials — see Authentication
An MCP-compatible AI assistant

Install

git clone https://github.com/tchopio/MCP tchop-mcp
cd tchop-mcp
npm install && npm run build

Configure

Set these environment variables when adding the MCP server to your assistant:

TCHOP_ORG_URLStringFull org host, e.g. acme.tchop.io REQUIRED

TCHOP_AUTH_TOKENStringYour authentication token REQUIRED

TCHOP_API_CLIENT_IDStringYour API client ID REQUIRED

TCHOP_ORG_SUBDOMAINStringOverride subdomain for staging environments OPTIONAL

Use in Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "tchop": {
      "command": "node",
      "args": ["/absolute/path/to/tchop-mcp/dist/index.js"],
      "env": {
        "TCHOP_ORG_URL": "<your-org>.tchop.io",
        "TCHOP_AUTH_TOKEN": "<your-token>",
        "TCHOP_API_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

Restart Claude Desktop after saving.

Use in Claude Code

claude mcp add tchop -- node /absolute/path/to/tchop-mcp/dist/index.js \
  -e TCHOP_ORG_URL=<your-org>.tchop.io \
  -e TCHOP_AUTH_TOKEN=<your-token> \
  -e TCHOP_API_CLIENT_ID=<your-client-id>

Use in Cursor

Create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "tchop": {
      "command": "node",
      "args": ["/absolute/path/to/tchop-mcp/dist/index.js"],
      "env": {
        "TCHOP_ORG_URL": "<your-org>.tchop.io",
        "TCHOP_AUTH_TOKEN": "<your-token>",
        "TCHOP_API_CLIENT_ID": "<your-client-id>"
      }
    }
  }
}

Get Started

GraphQL API

Call the tchop GraphQL API directly with three authentication headers and a standard POST request.

Endpoint

POST https://<your-org>.<env>/api/graphql/webapp

Required headers

Header	Description
`x-tchop-webapp-organisation`	Your org subdomain
`x-tchop-auth-token`	Your authentication token
`x-tchop-api-client-id`	Your API client ID

Example — curl

curl -X POST "https://<your-org>.tchop.io/api/graphql/webapp" \
  -H "content-type: application/json" \
  -H "x-tchop-webapp-organisation: <your-org>" \
  -H "x-tchop-auth-token: <your-token>" \
  -H "x-tchop-api-client-id: <your-client-id>" \
  -d '{"query":"query { organisation { id name subdomain } }"}'

Environments

Suffix	Environment	Example endpoint
`tchop-staging.com`	Staging	`https://acme.tchop-staging.com/api/graphql/webapp`
`.tchop.io`	Production	`https://acme.tchop.io/api/graphql/webapp`
`.tchop.it`	Production (EU)	`https://acme.tchop.it/api/graphql/webapp`

Concepts & Features

Organisation

An organisation is the root entity of every tchop deployment — one enterprise customer, one subdomain, one set of users.

It contains all channels, content, settings, and user management in a single isolated container.

tchop hierarchy

OrganisationTop-level container

→

ChannelAudience segment

→

MixContent feed

→

CardContent unit

API naming: In the API, a Mix is called a Story and a Card is called a StoryCard.

Subdomain

Each organisation has a globally unique subdomain used in all API requests as the x-tchop-webapp-organisation header value. The subdomain cannot be changed after users have joined without causing a breaking change.

Environments

Suffix	Environment	GraphQL endpoint
`tchop-staging.com`	Staging	`https://<org>.tchop-staging.com/api/graphql/webapp`
`.tchop.io`	Production	`https://<org>.tchop.io/api/graphql/webapp`
`.tchop.it`	Production (EU)	`https://<org>.tchop.it/api/graphql/webapp`

Basic settings

Field	Type	Description
`name`	String	Organisation display name shown in the app and admin console
`subdomain`	String	URL-safe subdomain slug. ⚠ Breaking Cannot be changed after users have joined
`localeId`	String	Default locale (e.g. `en`, `de`, `fr`)

Security

Field	Type	Description
`appLockEnabled`	Boolean	Require users to set a PIN lock when opening the app
`twoFactorForce`	Enum	Enforce 2FA for all org members. Options: `DISABLED`, `OPTIONAL`, `REQUIRED_EMAIL`, `REQUIRED_SMS`, `REQUIRED_APP`
`sessionExpirationTime`	Int	Web session expiry in seconds. `0` = never expire
`sessionExpirationTimeApp`	Int	Mobile app session expiry in seconds. `0` = never expire

User onboarding

Field	Type	Description
`invitingIntoDefaultChannelsEnabled`	Boolean	Auto-add new users to default channels on registration
`defaultChannelIds`	[Int]	Channel IDs that new users are added to automatically
`defaultChannelUserRoleId`	Int	Role assigned to new users in default channels

Content policies

Field	Type	Description
`restrictDuplicateUrlOfCards`	Enum	Prevent duplicate URLs from being posted within a window. Options: `DISABLED`, `LAST_1H`, `LAST_6H`, `LAST_12H`, `LAST_24H`, `LAST_2D`, `LAST_7D`, `LAST_30D`, `ALL_TIME`

Chat

Field	Type	Description
`chatPromotionEnabled`	Boolean	Show a banner promoting the chat feature to users who have not used it

App tabs

App tabs control the bottom navigation bar of the mobile app. Each tab can be enabled or disabled. 13 tab types are available:

Tab type	Description
`HOME`	Main news feed
`NOTIFICATIONS`	Notification center
`CHAT`	Direct and group messaging
`LEADERBOARD`	User engagement leaderboard
`PROFILE`	User profile page
`SEARCH`	Global content search
`EVENTS`	Events calendar
`DIRECTORY`	User directory
`LIBRARY`	Saved content library
`CUSTOM`	Custom tab with configurable URL
`CHANNEL`	Pinned channel tab
`STORY`	Pinned mix/story tab
`WEBVIEW`	Embedded web view

Configure tabs via appTabsSettings: an array of objects each with type (Enum), enabled (Boolean), and optional per-language labels.

Permissions (read-only)

Field	Description
`role`	The authenticated user's role in this organisation
`uuid`	Immutable organisation UUID
`id`	Immutable integer organisation ID
`createdAt`	Organisation creation timestamp

User roles

Role	Scope	Description
`Staff`	Cross-org	Internal tchop staff. Can create and delete organisations.
`Org Owner`	Organisation	Full control of the organisation including all settings and destructive operations.
`Org Admin`	Organisation	Manage org settings, channels, and users.
`Channel Admin`	Channel	Full control of specific channels they administer.
`Editor`	Channel	Create, edit, and publish content in assigned channels.
`Editor Limited`	Channel	Create and edit drafts. Cannot publish.
`Reader`	Channel	Consume content. No write operations.

Concepts & Features

Channels

📋

Coming soon

Detailed documentation for Channels is being written.

Concepts & Features

Mixes

📋

Coming soon

Detailed documentation for Mixes is being written.

Concepts & Features

Cards

📋

Coming soon

Detailed documentation for Cards is being written.

Concepts & Features

Users

📋

Coming soon

Detailed documentation for Users is being written.

Concepts & Features

Comments

📋

Coming soon

Detailed documentation for Comments is being written.

Concepts & Features

Tags

📋

Coming soon

Detailed documentation for Tags is being written.

Concepts & Features

Notifications

📋

Coming soon

Detailed documentation for Notifications is being written.

Concepts & Features

Analytics

📋

Coming soon

Detailed documentation for Analytics is being written.

Concepts & Features

Chat

📋

Coming soon

Detailed documentation for Chat is being written.

API Reference

Organisation

Operations for managing your tchop organisation. Click any card to expand full documentation.

create_organisation▼

Mutation⚠ Staff

Minimum role: Staff only

Create a new tchop organisation with a unique subdomain.

get_organisation▼

Query

Minimum role: Reader

Get full org details including all settings and app tab configuration.

create_organisation

⚠ Staff only

Restricted operation: Only internal tchop staff tokens can call this operation. Enterprise customers receive a permission error. This is documented for completeness and for tchop internal tooling.

Inputs

nameStringOrganisation display name, 3–24 characters REQUIRED

subdomainStringURL-safe subdomain, 3–24 characters, alphanumeric only. Must be globally unique. REQUIRED

Example call

{
  "name": "create_organisation",
  "arguments": {
    "name": "Acme Corp",
    "subdomain": "acme"
  }
}

Example response

{
  "id": 142,
  "name": "Acme Corp",
  "subdomain": "acme",
  "url": "https://acme.tchop.io",
  "role": { "id": 2, "name": "Org Owner" }
}

Edge cases ▼

Case	Behaviour
Subdomain already taken	Returns `SUBDOMAIN_TAKEN` error
Name too short (< 3 chars)	Validation error before request
Subdomain contains special characters	Validation error — alphanumeric only
Non-staff token	Returns 403 permission error

Mutation

mutation CreateOrganisation($name: String!, $subdomain: String!) {
  organisationCreate(input: {
    fields: { name: $name, subdomain: $subdomain }
  }) {
    id
    name
    subdomain
    uuid
    role { id name }
  }
}

Variables

{ "name": "Acme Corp", "subdomain": "acme" }

Example response

{
  "data": {
    "organisationCreate": {
      "id": 142,
      "name": "Acme Corp",
      "subdomain": "acme",
      "uuid": "c7f2e14a-1234-5678-abcd-ef0123456789",
      "role": { "id": 2, "name": "Org Owner" }
    }
  }
}

get_organisation

No inputs required. The org is derived from your TCHOP_ORG_URL.

Example call

{ "name": "get_organisation", "arguments": {} }

Example response

{
  "id": 142,
  "uuid": "c7f2e14a-1234-5678-abcd-ef0123456789",
  "name": "Acme Corp",
  "subdomain": "acme",
  "localeId": "en",
  "appLockEnabled": false,
  "chatPromotionEnabled": true,
  "twoFactorForce": "DISABLED",
  "sessionExpirationTime": 0,
  "sessionExpirationTimeApp": 0,
  "role": { "id": 2, "name": "Org Owner" },
  "appTabsSettings": [
    { "type": "HOME", "enabled": true },
    { "type": "NOTIFICATIONS", "enabled": true },
    { "type": "CHAT", "enabled": false }
  ]
}

Edge cases ▼

Case	Behaviour
Invalid or expired token	Returns 401 authentication error
Wrong org header value	Returns 404 organisation not found

Query

query GetOrganisation {
  organisation {
    id
    uuid
    name
    subdomain
    localeId
    appLockEnabled
    chatPromotionEnabled
    twoFactorForce
    sessionExpirationTime
    sessionExpirationTimeApp
    invitingIntoDefaultChannelsEnabled
    defaultChannelIds
    defaultChannelUserRoleId
    restrictDuplicateUrlOfCards
    role { id name }
    appTabsSettings {
      type
      enabled
      labels { language label }
    }
  }
}

update_organisation▼

Mutation

Minimum role: Org Admin

Update organisation settings. All 14 fields are optional — only what you provide is changed.

delete_organisation▼

Mutation⚠ Staff

Minimum role: Staff only

Permanently delete an organisation and all its data. Irreversible.

update_organisation

All fields optional. Only fields you include are changed.

Inputs

nameStringOrganisation display name OPTIONAL

localeIdStringDefault locale code OPTIONAL

appLockEnabledBooleanEnable app lock PIN screen OPTIONAL

twoFactorForceEnumDISABLED | OPTIONAL | REQUIRED_EMAIL | REQUIRED_SMS | REQUIRED_APP OPTIONAL

sessionExpirationTimeIntWeb session expiry in seconds. 0 = never OPTIONAL

sessionExpirationTimeAppIntApp session expiry in seconds. 0 = never OPTIONAL

invitingIntoDefaultChannelsEnabledBooleanAuto-add new users to default channels OPTIONAL

defaultChannelIds[Int]Channel IDs for new user auto-join OPTIONAL

defaultChannelUserRoleIdIntRole ID for default channel membership OPTIONAL

restrictDuplicateUrlOfCardsEnumDISABLED | LAST_1H | LAST_6H | LAST_12H | LAST_24H | LAST_2D | LAST_7D | LAST_30D | ALL_TIME OPTIONAL

chatPromotionEnabledBooleanShow chat promotion banner OPTIONAL

appTabsSettingsArrayApp tab configuration — array of objects with type, enabled, and optional labels OPTIONAL

Example call

{
  "name": "update_organisation",
  "arguments": {
    "twoFactorForce": "REQUIRED_APP",
    "appLockEnabled": true,
    "chatPromotionEnabled": false
  }
}

Example response

{
  "id": 142,
  "name": "Acme Corp",
  "twoFactorForce": "REQUIRED_APP",
  "appLockEnabled": true,
  "chatPromotionEnabled": false
}

Edge cases ▼

Case	Behaviour
Invalid enum for twoFactorForce	Validation error before request
Insufficient role (Editor or Reader)	Returns 403 permission error
Empty arguments object	Succeeds with no changes applied
Invalid defaultChannelIds	Error if IDs don't belong to this org

Mutation

mutation UpdateOrganisation(
  $name: String,
  $twoFactorForce: TwoFactorForceType,
  $appLockEnabled: Boolean,
  $chatPromotionEnabled: Boolean,
  $appTabsSettings: [AppTabSettingsInput]
) {
  organisationUpdate(input: {
    fields: {
      name: $name
      twoFactorForce: $twoFactorForce
      appLockEnabled: $appLockEnabled
      chatPromotionEnabled: $chatPromotionEnabled
      appTabsSettings: $appTabsSettings
    }
  }) {
    id name twoFactorForce appLockEnabled chatPromotionEnabled
  }
}

Variables

{
  "twoFactorForce": "REQUIRED_APP",
  "appLockEnabled": true
}

delete_organisation

⚠ Staff only

Irreversible. Permanently deletes the organisation, all channels, all content, and all users. Cannot be undone.

Inputs

confirmBooleanMust be explicitly true. The MCP will prompt for confirmation before executing. REQUIRED

Example call

{
  "name": "delete_organisation",
  "arguments": { "confirm": true }
}

Edge cases ▼

Case	Behaviour
`confirm` not set or `false`	Operation aborted — explicit confirmation required
Non-staff token	Returns 403 permission error immediately
Organisation not found	Returns 404 not found

Mutation

mutation DeleteOrganisation($confirm: Boolean!) {
  organisationDelete(input: { confirm: $confirm }) {
    success
  }
}

Variables

{ "confirm": true }

API Reference

Channels

🔧

Coming soon

Channels API operations are being documented.

API Reference

Mixes

🔧

Coming soon

Mixes API operations are being documented.

API Reference

Cards

🔧

Coming soon

Cards API operations are being documented.

API Reference

Users

🔧

Coming soon

Users API operations are being documented.

API Reference

Comments

🔧

Coming soon

Comments API operations are being documented.

API Reference

Tags

🔧

Coming soon

Tags API operations are being documented.

API Reference

Notifications

🔧

Coming soon

Notifications API operations are being documented.

API Reference

Analytics

🔧

Coming soon

Analytics API operations are being documented.

API Reference

Chat

🔧

Coming soon

Chat API operations are being documented.