MCP Server

Connect AI assistants like Claude or ChatGPT to your Business Platform projects via the Model Context Protocol (MCP)

mcpaiclaudechatgptapiintegrationoauth

The Business Platform exposes a remote Model Context Protocol (MCP) server that lets you connect AI assistants — such as Claude, ChatGPT, or any MCP-compatible client — directly to your projects. Once connected, you can use natural language to create projects, define data types, query data, create entries, update records, and more.

The MCP server is available to every authenticated user — no feature flag or administrator setup required.

Quick start

  1. Open your AI client's connector settings (e.g. Claude: Settings > Connectors > Add custom connector)
  2. Add the server URL: https://platform.smallstack.com/mcp
  3. Your browser opens — log in with your usual account
  4. Approve the consent screen ("Allow [client] to access your projects?")
  5. Start talking to your data: "Create a project where I can manage all my real estates"

Tip: The backoffice has a built-in connect page at /mcp/connect with a copy button for the connector URL and per-client instructions.

Authentication

The MCP server uses OAuth 2.1 for authentication. MCP-compatible clients handle this automatically — you do not need to manage tokens manually.

The flow works like this:

  1. Your AI client connects to https://platform.smallstack.com/mcp
  2. The server responds with OAuth discovery metadata and the client registers itself automatically (dynamic client registration)
  3. Your client opens a browser window for you to log in
  4. You see a consent screen listing the permissions the client is requesting
  5. After approval, your client receives a token and uses it for all subsequent requests

Supported OAuth scopes:

Scope Description
openid Identify you
profile Read your profile information
email Read your email address
offline_access Keep your client connected via refresh tokens (no repeated sign-in)

Available tools

Once connected, your AI assistant has access to the following tools. Every tool is backed by the platform's regular HTTP API, so all calls respect your existing permissions — you can only access data you would normally see in the backoffice.

project_list

Lists all projects you have access to.

Example prompt: "What projects do I have?"

project_create

Creates a new project owned by you, including default roles and a default dashboard.

Parameter Required Description
name Yes The project name

Example prompt: "Create a project called Real Estate Portfolio"

type_list

Lists all data types defined in a specific project.

Parameter Required Description
projectId Yes The project ID

Example prompt: "What data types are in project X?"

type_create

Defines a new data type in a project — the schema describes the fields your entries will have. Access configuration is always generated server-side; an AI client cannot grant wider access than the platform default.

Parameter Required Description
projectId Yes The project ID
title Yes Plural display name (e.g. "Real Estates")
titleSingular Yes Singular display name (e.g. "Real Estate")
schema Yes JSON schema of the fields (e.g. { "type": "object", "properties": { "address": { "type": "string" } } })
icon No FontAwesome icon class (e.g. fa-building)
representationText No Entry display template referencing fields as #{fieldName}

Example prompt: "Add a real-estate type with address, size and purchase price fields"

type_get_schema

Returns the full merged schema of a type so the assistant can construct valid data payloads.

Parameter Required Description
projectId Yes The project ID
typeId Yes The type ID (from type_list / type_create)

data_query

Queries data entries of a specific type.

Parameter Required Description
projectId Yes The project ID
typeId Yes The type ID

Example prompt: "Show me all real estates in my portfolio project"

data_create

Creates a new data entry in a project.

Parameter Required Description
projectId Yes The project ID
typeId Yes The type ID
data Yes The field values for the new entry

Example prompt: "Add the property Hauptstraße 1, Berlin with 120 sqm"

data_update

Updates an existing data entry by ID.

Parameter Required Description
projectId Yes The project ID
typeId Yes The type ID
id Yes The entry ID
modifier Yes MongoDB-style modifier (e.g. { "$set": { "name": "New Name" } })

Example prompt: "Update the size of the Hauptstraße property to 130 sqm"

data_delete

Deletes a data entry by ID (soft delete).

Parameter Required Description
projectId Yes The project ID
typeId Yes The type ID
id Yes The entry ID

Example prompt: "Delete the Hauptstraße property"

Permissions and security

  • All operations run through the platform's regular HTTP API and enforce row-level security (RLS) — you can only read, update, or delete data you have permission to access
  • Type creation never accepts client-supplied access configuration — access defaults are generated server-side
  • Data creation respects the type's defaultAccess and creationAccess configuration
  • Tokens are short-lived JWTs validated against the platform's JWKS endpoint
  • Project creation is refused for accounts where an administrator has disabled it

Supported clients

Any client that supports the MCP Streamable HTTP transport can connect. Tested clients include:

  • Claude (claude.ai / Desktop) — Settings > Connectors > Add custom connector
  • Claude Code — add to .claude/settings.json or .vscode/mcp.json
  • ChatGPT — Settings > Connectors > add a custom MCP connector
  • Custom integrations — any HTTP client that implements the MCP protocol

Troubleshooting

Issue Solution
401 Unauthorized Your client could not complete the OAuth flow. Check that the server URL is exactly https://platform.smallstack.com/mcp and that your browser can reach the login page.
Permission denied on a tool call You do not have RLS access to the requested resource. Check your project permissions in the backoffice.
Project creation refused An administrator has disabled project creation for your account.
No projects returned Verify you have at least read access to a project.
  • AI Features — enabling AI capabilities per project
  • AI Agents — configurable AI agents within the platform
  • MCP Technical Reference — OAuth 2.1 authentication details for developers integrating directly with the MCP endpoint
Markdown | llm.txt