MCP server.
Connect an AI client to your Mosaik workspace with the Model Context Protocol, using one HTTPS endpoint and an API key.
The Mosaik MCP server connects an AI client to your workspace. The client reads records, and it changes records when the account can write. It uses the Model Context Protocol over streamable HTTP.
Endpoint
Each workspace serves the endpoint on its own address:
https://<your-portal>.example.com/mcpReplace <your-portal> with the address of your workspace. Settings → MCP in your workspace shows the exact endpoint to copy.
Send POST requests only. Another method returns 405 and sets Allow: POST.
Sign in
Send a Mosaik API key in the x-api-key header. Create a key in Settings → API keys. The key acts as the account that created it, so it has that account’s permissions.
A request with no key and no session returns a JSON-RPC 401. A signed-in user who is not a workspace member returns 403.
Keep the key secret. Revoke a key in Settings → API keys when it is no longer needed.
Connect a client
Use a client that supports a remote streamable HTTP server. Give the client the endpoint URL and this header:
x-api-key: <your-api-key>List the tools in the client. The client shows the tools below.
Read tools
| Tool | Use it to |
|---|---|
search_records |
Search companies, contacts, and deals by name, domain, or email. |
list_companies |
List active companies, newest activity first. |
list_contacts |
List active contacts. |
list_deals |
List active deals, and filter by status or stage. |
list_finance |
List invoices, payments, and subscriptions. |
get_company |
Read one company with its contacts and deals. |
get_contact |
Read one contact with its company. |
get_deal |
Read one deal with its stage, amount, and contacts. |
get_finance |
Read one invoice, payment, or subscription. |
Write tools
These tools change records. An account must be able to write records to see them. A preview deployment removes the write tools for every account.
| Tool | Use it to |
|---|---|
create_company |
Create a company. |
create_contact |
Create a contact. |
create_deal |
Create an open deal on an existing company. |
set_deal_stage |
Move a deal to another stage. |
log_activity |
Log a note, call, email, meeting, or task on a company, contact, or deal. |
A viewer account gets the read tools only. The write tools are absent from its tool list.
The server has no delete tool. No tool removes a record. There is no Finance write tool, so Finance records are read-only over MCP.
Limits
Each API key gets 60 requests in a rolling 60 seconds. A session without an API key gets the same limit for each user.
Every API instance shares the count. A refused request returns HTTP 429 with a JSON-RPC error code of 429. The response sets Retry-After to the seconds until the oldest request leaves the window.
A request that fails authentication does not count toward the limit.