> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pretectum.io/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Connect Claude Code, Cursor, VS Code and other AI assistants to your Pretectum data through the Model Context Protocol
The Pretectum MCP server exposes the public API to AI assistants through the [Model Context Protocol](https://modelcontextprotocol.io). Once connected, an assistant can browse your business areas, schemas and datasets, look records up, search across your master data, and create, update or delete records - with your API key or your own access token, so it can do exactly what that credential's roles and business area assignments allow, and nothing more.
## Endpoint
```
https://mcp.pretectum.io/mcp
```
The server speaks the Streamable HTTP transport. Every request is a `POST`; there is no session to keep open.
## Authentication
The server authenticates with the same credentials as the REST API: an API key, or the access token of a signed-in Pretectum user. Send either in the `Authorization` header of every request, exactly as you would to the API:
```bash theme={null}
Authorization: pre_your_api_key
```
`Bearer ...` is accepted as well. Create a key in the Pretectum app under **Configuration → API Keys**; see [API Keys](/api-reference/authentication/api-keys) for how keys are granted access. With an access token the assistant acts as that user, with the user's own roles and business areas, and every change is audited under the user's name.
Clients that support OAuth can sign you in instead of taking a header: add the server URL with no credential and, when the client offers to authenticate, sign in with your Pretectum account. The assistant then acts as you.
Your assistant acts with the credential's full permissions, including `update` and `delete` where its roles allow them. With a key, create one for the assistant, give it only the business areas it needs, and prefer a read-only role unless you want it to change data. With your own access token the assistant holds every permission you have - a tenant administrator's included - so prefer a scoped key for anything beyond reading.
Any MCP client that can send a custom header to a remote server works with a key. claude.ai custom connectors, Claude Code and the MCP inspector can sign you in instead.
## Connecting
In claude.ai open **Settings → Connectors → Add custom connector**. Name it Pretectum, enter `https://mcp.pretectum.io/mcp` as the URL, leave the OAuth client id and secret empty, and connect. You are sent to the Pretectum sign-in; once back, the tools are available in every chat where the connector is enabled, and in Claude Code for the same account.
With a key:
```bash theme={null}
claude mcp add --transport http --scope user pretectum https://mcp.pretectum.io/mcp \
--header "Authorization: pre_your_api_key"
```
Or by signing in, with a fixed callback port (the sign-in only accepts registered callbacks, and `3118` is one of them):
```bash theme={null}
claude mcp add --transport http --scope user --callback-port 3118 pretectum https://mcp.pretectum.io/mcp
```
then `/mcp` inside a session and **Authenticate**.
`--scope user` makes the server available in every project on the machine; use `--scope project` to write it to `.mcp.json` in a repository instead (keep the key out of source control in that case by referencing an environment variable, `--header "Authorization: ${PRETECTUM_API_KEY}"`).
Check it connected:
```bash theme={null}
claude mcp list
```
Inside a session, `/mcp` shows the server and its tools.
Create or edit `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for every project):
```json theme={null}
{
"mcpServers": {
"pretectum": {
"url": "https://mcp.pretectum.io/mcp",
"headers": {
"Authorization": "pre_your_api_key"
}
}
}
}
```
Cursor lists the server under **Settings → MCP** once the file is saved.
Create or edit `.vscode/mcp.json` in your workspace:
```json theme={null}
{
"servers": {
"pretectum": {
"type": "http",
"url": "https://mcp.pretectum.io/mcp",
"headers": {
"Authorization": "pre_your_api_key"
}
}
}
}
```
Start the server from the **MCP Servers** view or the code lens above the entry; the tools then appear in agent mode.
## Tools
Each tool maps to one endpoint of the public API.
| Tool | What it does | Endpoint |
| - | - | - |
| `list_business_areas` | Business areas the key can reach | [List Business Areas](/api-reference/business-areas/list) |
| `list_schemas` | Schemas in a business area | [List Schemas](/api-reference/schemas/list) |
| `get_schema` | A schema's fields, as a guide to writing records: names, types, required and primary key flags, picklist values, date formats | [Get Schema](/api-reference/schemas/get) |
| `list_datasets` | Datasets of a schema, with record counts | [List Datasets](/api-reference/datasets/list) |
| `list_data_objects` | Page through a dataset's records | [List Data Objects](/api-reference/dataobjects/list) |
| `get_data_object_by_primary_key` | Fetch one record by its primary key value | [Get Data Object by Primary Key](/api-reference/dataobjects/get-by-primary-key) |
| `search_data_objects` | Search across business areas, schemas and datasets by text or field conditions | [Search Data Objects](/api-reference/dataobjects/search) |
| `create_data_object` | Create a record | [Create Data Object](/api-reference/dataobjects/create) |
| `update_data_object` | Change fields of a record, guarded by its `_version` | [Update Data Object](/api-reference/dataobjects/update) |
| `delete_data_object` | Delete a record | [Delete Data Object](/api-reference/dataobjects/delete) |
The server tells the assistant how the pieces fit together: to walk the hierarchy for ids, to read the schema before writing, to send the record's current `_version` on every update and to re-read on a conflict, and to confirm with you before deleting anything.
## Example Conversation
Once connected, ask in plain language:
* *"Which business areas can you see?"*
* *"Find every customer in the US Customers dataset with an example.com email."*
* *"Look up customer CUST-000123 and change their status to Inactive."*
* *"Create a new supplier record for Acme Ltd - ask me for any required field you don't have."*
The assistant calls the tools in turn, showing you each result. Every call is audited under your key, or under your name when you connected with a token, like any other API request.
## Troubleshooting
| Symptom | Cause | Fix |
| - | - | - |
| The client reports it was refused (`401`) before any tool runs | The `Authorization` header is missing, or the value looks like neither a Pretectum key nor an access token | Send `pre_...` or the token (optionally behind `Bearer`) in the header |
| Tools answer `Pretectum API error [401]` | The key is unknown, inactive, expired or deleted; or the access token is invalid or has expired | Check the key under **Configuration → API Keys**, or sign in again for a fresh token |
| Tools answer `Pretectum API error [403]` | The key, or the signed-in user, lacks a role or a business area assignment | Ask your tenant administrator |
| `list_business_areas` returns nothing | The key or user has no business area assignment | Same |
| Sign-in ends on a Cognito error page mentioning `redirect_uri` | The client's callback URL is not one the Pretectum sign-in accepts | In Claude Code pass `--callback-port 3118`; for another client, ask Pretectum support to register its callback |
| An update answers `DATA_OBJECT_VERSION_CONFLICT` | The record changed after the assistant read it | The assistant re-reads and retries; nothing was written |
## Related
Create and manage the key your assistant uses, or read how a token compares
The endpoints behind each tool