# Mockomat AI Capabilities

> **Version:** 1.1
> **Updated:** 2026-05-10

## What is Mockomat?

Mockomat generates fully queryable GraphQL mock APIs from user-defined schemas. It serves realistic data sourced from open-licensed datasets and synthetic generators — ideal for frontend development, prototyping, testing, and AI-driven applications.

## AI Integration

### MCP Server

Mockomat exposes a Model Context Protocol (MCP) server that AI agents can connect to for:

- **Project management** — create, list, and configure mock API projects
- **Schema modelling** — define tables, attributes, relations, and views
- **Data operations** — query, filter, sort, and paginate mock data
- **OpenAPI import** — import existing specs to scaffold a complete mock API
- **Code generation** — generate typed client code (Angular + NestJS)

### Anonymous Sessions

AI agents can create anonymous guest sessions without authentication. No signup, no API key, no configuration. A session cookie is the only identity.

Anonymous users are stored as real `User` records with `role=anonymous` and a `sessionId`. They are first-class participants — they can own a session project, join other projects as collaborators, and author board notes and comments. JWTs are issued so anonymous identity persists across page reloads.

### Public GraphQL Endpoint

```
POST https://api.mockomat.com/public-graphql
Content-Type: application/json
```

The cookie jar must persist across requests (curl: `-c cookies.txt -b cookies.txt`).

Available mutations (no authentication required):

- `createSessionProject` — create a guest project (returns `id`, `slug`, `collaborationToken`, `previewToken`)
- `createModellingTable(input: { projectId, name, plural, position })` — define an entity
- `createModellingAttribute(input: { tableId, name, scalarType })` — define a field
- `createModellingRelation(input: { projectId, sourceTableId, targetTableId, relationType, fieldName })` — FK relation
- `generateDefaultGqlOperations(projectId)` — generate CRUD operations
- `generateMissingViews(projectId)` — generate list/detail views
- `importOpenApiSpec(input: { specContent, selectedSchemas, createNewProject })` — import an OpenAPI 3.x spec
- `createBoardNote(input: { projectId, positionX, positionY, title })` — add a board note
- `addBoardNoteComment(input: { noteId, text })` — comment on a note

Available queries:

- `sessionProject` — current project status (owner perspective)
- `project(id)` — fetch a specific project (works for collaborators too)
- `modellingTablesByProject(projectId)` — list tables
- `modellingRelationsByProject(projectId)` — list relations
- `availableDataSources` — browse curated real-world datasets

### Typical Workflow

1. `createSessionProject` — get projectId + slug + collaborationToken
2. Create tables, attributes, and relations (or import an OpenAPI spec)
3. `generateDefaultGqlOperations` — generate CRUD operations
4. `generateMissingViews` — generate views
5. Query data at the mock runtime endpoint
6. Return the collaboration URL to the developer: `https://app.mockomat.com/s/{slug}/collaborate?token={collaborationToken}`

Total: 5-12 API calls for a complete mock API. Sessions expire after 24 hours.

### Real-Time Collaboration with Humans

AI agents can collaborate with humans on the same project in real time. Two patterns:

**Pattern A — AI creates, human joins:**
1. Agent creates session project via the workflow above
2. Agent returns the collaboration link to the human
3. Human opens the link → joins as a new anonymous user
4. Both see live updates via Server-Sent Events

**Pattern B — Human creates, AI joins:**
1. Human shares their collaboration link with the agent
2. Agent posts to `POST /collaborate/{slug}/join?token={collaborationToken}` to get a JWT
3. Agent uses the JWT on subsequent `/public-graphql` calls (cookie jar must persist)
4. Both see live updates via SSE

Both patterns use the same identity model: anonymous `User` rows with per-session JWTs, attributed to board notes/comments.

### Mock Runtime Endpoint

```
POST https://api.mockomat.com/mock/{slug}/graphql
Content-Type: application/json
```

Guest projects with public preview access require no API key. Paid projects require `Authorization: Bearer mck_*` and `X-Actor-Token` headers.

## Workspaces and URL Structure

Projects belong to a workspace. Authenticated users get tenant workspaces; anonymous users get a synthetic in-memory "Session" workspace. Both follow the same URL pattern:

- Project board: `https://app.mockomat.com/w/{wsSlug}/p/{projectId}/modelling`
- Project list: `https://app.mockomat.com/w/{wsSlug}/projects`

For collaboration and preview, the workspace is implicit — the project slug is enough:

- Collaborate: `https://app.mockomat.com/s/{slug}/collaborate?token={collaborationToken}`
- Preview: `https://app.mockomat.com/s/{slug}/preview?token={previewToken}`

## Rate Limits

| Endpoint | Limit |
|----------|-------|
| Public mutations | 30 req/min |
| OpenAPI import | 10 req/min |
| Mock runtime | 60 req/min |

## Supported Spec Formats

- OpenAPI 3.0.x / 3.1.x (YAML or JSON)
- Max spec size: 1 MB

## Permissions

Permissions are DB-driven, not hardcoded. Each action (e.g. `modelling.table.create`, `apikey.create`) has a `minWorkspaceRole`, `minPlanTier`, and `requiresProjectAccess` configured by administrators in Settings → Permissions. Anonymous users interact via `/public-graphql` where access is enforced per-request via session/collaborator records — the centralized permission table governs registered users on `/graphql`.

## Links

- Documentation: https://docs.mockomat.com
- MCP Setup: https://app.mockomat.com/mcp
- Website: https://www.mockomat.com