Connecting Claude & Cockpit (MCP)

New to the team?

Not the entry point for a new website in v0. First Start here and optionally Claude & MCP — only later.

With this connection, you communicate with Cockpit in normal sentences in Claude: read, search, create content, create centers, and submit or approve drafts. The program is called MCP (Model Context Protocol).

Tool names (from MCP v0.5.0)

Write/integration tools are named cockpit_* (e.g. cockpit_content_push, cockpit_list_centers) — no longer cockpit_agencyos_*. After MCP deploy, re-enable the v0 MCP connector and update Custom Instructions / tool names (see packages/mcp-cockpit-os/V0_CUSTOM_INSTRUCTIONS.md).

Important if you work a lot with v0 and Claude

Not everything goes through MCP. Social media, Content Planner, and Dispatch are handled in the Cockpit dashboard — Claude cannot replace those (as of today). See v0, Claude/MCP and Cockpit — who does what?.

There are two ways. Take Way A if you have Claude Pro/Team/Enterprise — it requires zero installation on your Mac.

---

v0, Claude/MCP and Cockpit — who does what?

Editorial teams will work heavily via v0 and Claude — still, there are three separate layers. Do not mix them up, or you will look for social posts or the calendar in chat in vain.

Three layers at a glance

Layer	For what	Entry point
v0	Website design: layout, components, colors. Content comes from the Cockpit API (Instructions A–J).	Center website with v0
Claude + MCP	Read/write center data: news, events, offers, shops, website tabs, workflow drafts	This page
Cockpit dashboard	Social (Outstand), calendar, approval boards, dispatch, engage, reporting	Navigation & modules

Rule of thumb: v0 = look & feel. MCP = content & config in the database. Dashboard = social, planner, email inbox.

Via MCP / Claude — this works ✅

Area	Example prompt / tool
News, events, offers, shops	cockpit_search_content, cockpit_content_push with submitToWorkflow: true
Website tabs (hero, header, colors, MEC ShopBox …)	cockpit_website_config_schema → read/write
Create & update centers	cockpit_create_center, cockpit_update_center
Media library, homepage tiles	cockpit_upload_media, cockpit_homepage_tiles
Website workflow (approvals)	cockpit_list_drafts, cockpit_update_draft
Website/content analytics	cockpit_analytics_* — full Umami (traffic, events, export, browser/OS/countries), content performance, signage, reporting, trending (not social Outstand KPIs)
Check public live data	cockpit_public_news, cockpit_public_offers, …

Not via MCP — use the dashboard 🖥️

These areas have no MCP tools. Claude cannot read or control them — even when the connector is connected.

Area	Dashboard path	Why
Social posts (create, schedule, AI image)	Social Cockpit → Create post (/dashboard/social/new)	Outstand, channels, media editor
Social approvals	/dashboard/social/approvals	Separate board — not website workflow
Community & replies (Engage)	/dashboard/social/engage	Comments from Outstand, post replies
Social performance (+ PDF export)	/dashboard/social/reporting	Outstand metrics, period filter
Link channels	/dashboard/settings/social-accounts	OAuth / IT setup
Content Planner (calendar, “online only”)	/dashboard/content/planner	Calendar UI; MCP can create content but not operate the planner
Dispatch (email inbox)	Editorial flow → Dispatch	Inbox UI
Emoji picker / image lightbox	Social editor	Browser UI only

Typical day

1. Offer or news → Claude/MCP (draft for approval) or manually in Cockpit.
2. Check calendar slot → open Content Planner in the browser.
3. Facebook/Instagram post → Social Cockpit (editor → approval → Outstand).
4. New layout / hero slide → v0 for code; tab texts optionally via MCP (templateContent).

v0 and MCP complement each other

In v0, Instructions (parts A–J) load news, events, and shops via the public API. Claude writes the same data into Cockpit via MCP. v0 does not replace MCP — and MCP does not replace v0 design.

Question	Answer
What does the page look like?	v0 (+ deploy via GitHub/Vercel)
What is in news/offers/tabs?	MCP or manually in the dashboard
Social post or reply to a comment?	Dashboard → Social Cockpit
When does which offer appear in the calendar?	Dashboard → Content Planner

Read more: Social media — getting started · Social approvals (detail) · Workflow & planner

---

Way A — Remote URL (recommended · no installation)

Who can use this

Claude Pro, Team, or Enterprise — that is, a paid Claude account on claude.ai. Claude Free is not sufficient for this way.

This runs once — IT sets up the server (see IT setup below), then every editor only needs 2 clicks + fill out 2 fields.

For the editor: 3 steps

What you need from IT — a single URL

IT sends you a ready URL that already contains the token — e.g.:

https://mallos-mcp-cockpit.onrender.com/mcp?token=a3f7b9...

You don’t need to remember the token separately. The URL is your access — keep it secret like a password.

Step 1 — Open Claude
Open claude.ai in your browser and log in.

Step 2 — Enter connector
Click on your profile picture in the top right → Settings → on the left Connectors (or “Integrations" / “MCP" — the name may vary slightly depending on the Claude version).

→ Add custom integration (or “Add MCP server") → fill out the following fields:

Field	What you enter
Name	cockpitOS (or any name)
Server URL	the complete URL from IT (with ?token=… at the end)
Advanced Settings (OAuth fields)	leave blank — not needed

→ Click Save.

Step 3 — Check
Type in the Claude chat:

Please call the tool cockpit_public_center_by_slug with the slug "your-center-slug". What is the center name and what is the centerId?

If Claude responds with a name and ID: everything works. 🎉

---

Examples — what you can tell Claude

Start a new center website project (mandatory entry)

Whenever a new website project for a center begins, first do this step:

I'm starting a new center website project for the center with the slug "YOUR-SLUG".
Please call cockpit_center_project_init with (center_slug="YOUR-SLUG", api_base_url="https://dashboard.cockpit-os.de").
Show me the centerId and the checklist.

Claude then provides:

• centerId (UUID) for all further API calls
• A checklist of mandatory steps (activate website, configure analytics, review content, …)
• Warnings if the center doesn't exist or has no content

Why this step is mandatory

The tool ensures that Claude knows: cockpitOS is the only Source of Truth. Shops, news, events, and texts should never exist as dummy data in the frontend code — they always come from cockpitOS. The init step actively loads this rule into the AI context.

Get an overview of a center

I work for our shopping center (Slug: "YOUR-SLUG").
1. Get the centerId via cockpit_public_center_by_slug.
2. Show me a compact overview: active shops, ongoing offers, upcoming events.
   Use cockpit_content_stats for that.
Don't write anything in Cockpit yet.

Load center plan (including hybrid SVG)

Slug "YOUR-SLUG". Get centerId via cockpit_public_center_by_slug and then cockpit_public_wayfinding_floors.
List per floor: name, length mapSvg drawings, whether mapImage and shopViewBoxes are set, number of mapLocations.

See also: Public API Contract — Hybrid & Wayfinding.

Search for content before creating anything

Are there already offers from Deichmann in our Cockpit? Please search in all centers.
Use cockpit_search_content with q="Deichmann" and contentType="offer".

Which offers are expiring in the next 7 days?
Use cockpit_search_content with contentType="offer" and expiresBefore="<Date in 7 days>".

Submit offer for all centers of a chain (workflow mode)

In workflow mode, everything first goes under Workflow & Approvals in the dashboard — nothing goes live until someone approves it.

Always get a preview first (no writing, only data check):

Use cockpit_content_push_preview for center <UUID> with:
offers: [{ title: "Summer Sale: 30% off all sneakers", description: "...", validFrom: "2026-07-01", validTo: "2026-07-31" }]

Show me what Cockpit returns — not really submitting yet.

If the preview is correct, then submit for all Deichmann centers:

Create an offer for all Deichmann centers:
- Title: "Summer Sale: 30% off all sneakers"
- Valid: July 1 to July 31

Step 1: Use cockpit_list_centers with chainSlug="deichmann".
Step 2: For each center: cockpit_content_push with submitToWorkflow=true and campaignLabel="Summer Sale Deichmann July".
Show me a preview for each center first.

What happens next: In Workflow & Approvals all drafts appear — filterable by campaign, with an "Approve All" button.

Create a new center on the fly

You no longer need to create a center in the dashboard beforehand — Claude can do it directly:

Create a new center in Cockpit:
- Name: Alstertal Shopping Center
- Address: Heegbarg 31, 22391 Hamburg
- Logo: https://example.com/logo.png (please upload to BunnyCDN)
- Accent color: #E63946

Afterward: show me the centerId and the slug.

Immediately after, you can fill it:

Add the following shops for the newly created center (centerId: ...):
- H&M (Category: Fashion, Floor: Ground Floor)
- Starbucks (Category: Gastronomy, Floor: Ground Floor)
Use cockpit_list_categories to get the right category names.

Update center logo or opening hours

Update the following for center X (centerId: ...):
- New logo: https://... (please upload to BunnyCDN)
- Opening hours: Mon–Sat 10 am–9 pm, Sun 12 pm–6 pm

The Deichmann logo has changed. Here is the new logo: https://...
Please update the logo for all centers that have a Deichmann shop.

Review and approve drafts

How many drafts are currently waiting for approval?
Use cockpit_list_drafts.

Approve all drafts from the campaign "Summer Sale Deichmann July".
1. First, get the drafts with cockpit_list_drafts and campaignLabel="Summer Sale Deichmann July".
2. Approve each one with cockpit_update_draft.

Clean up expired content

Show me all offers that have already expired (endDate before today).
Use cockpit_search_content with contentType="offer" and expiresBefore="<today>".
Then: archive all of them with cockpit_archive_content.

---

Overview of MCP tools

Complete tool list

The authoritative reference of all registered tools is in packages/mcp-cockpit-os/README.md and in the source code packages/mcp-cockpit-os/src/register-cockpit-tools.ts. The tables below are an editorial selection — not every public read route is listed individually.

Public Reads (without API Key, selection)

Tool	What it does
cockpit_public_center_by_slug	Slug → centerId, Name
cockpit_public_news / events / offers	Lists including contentCategory; Filter contentCategorySlug
cockpit_public_content_categories	Content categories (News/Events/Offers)
cockpit_public_aktuelles_bundle	News+Events+Offers+Jobs in one request
cockpit_public_wayfinding_floors	Center plan with mapSvg, mapLocations
cockpit_public_shops / services / offices	Master data
cockpit_public_integration_docs	Machine-readable integration instructions for v0

Project Entry (new)

Tool	What it does
cockpit_center_project_init	Mandatory entry for every new center website project. Checks if the center exists, returns centerId, and provides a 7-step checklist + quick reference for the workflow. Prevents content from only landing in the frontend code.
cockpit_mcp_discover_tools	Tool Finder: If Claude does not find an MCP tool (tool_search shows only ~5 out of 70+ tools) — enter a keyword, get the exact tool name.

Website tab & configuration

Tool	What it does
cockpit_get_center_website_config	Read full website config (Design, SEO, templateContent, pagesConfig, …).
cockpit_website_config_schema	Dashboard tabs per template: where which fields lie + which MCP tool.
cockpit_update_center_website_config	Write website config (partial update).

Read & navigate

Tool	What it does
cockpit_public_center_by_slug	Resolve center by URL slug → returns centerId, name. No API Key needed.
cockpit_public_wayfinding_floors	Center plan / interactive map: floors with mapSvg and mapLocations (e.g., for SVG-click → Shop-modal). centerId = Center UUID, not floorId from the center plan URL.
cockpit_list_centers	List all centers — filterable by chain (chainSlug), organization (organizationId), name.
cockpit_get_center	Details of a center by ID.
cockpit_center_context	Complete Cockpit context (shops, news, events, offers, services); optionally include=content_categories
cockpit_list_organizations	All organizations with center count.
cockpit_list_categories	Available shop categories — call before creating shops.

Search

Tool	What it does
cockpit_search_content	Full-text search over news, offers, events, shops, services, jobs, offices — with keyword, status, and date filters. Returns createdAt, updatedAt, source (where available).
cockpit_content_stats	Compact overview: active shops, offers, events, open drafts, what is soon expiring.
cockpit_audit_logs	Provenance: Who changed which content when — per center or per entry. With summary: true → leaderboard by user.
cockpit_center_team	Team: Who is assigned to the center (roles, permissions) — answers "how many are working on it?".

Manage centers

Tool	What it does
cockpit_create_center	Create new center (name, address, logo, colors …).
cockpit_update_center	Update center metadata — logo, opening hours, colors, hero image, SEO.

Write content

Tool	What it does
cockpit_content_push_preview	Preview / Dry-Run — shows what would happen on push, writes nothing. Always call first.
cockpit_content_push	Writes to Cockpit — directly or with submitToWorkflow: true for approval.
cockpit_chain_bulk	Create the same content for all centers of a chain (e.g., all Deichmann centers).
cockpit_org_bulk	Create the same content for all centers of an organization.
cockpit_archive_content	Archive content (shops, events, news, offers, services).
cockpit_upload_media	Upload external image URL to BunnyCDN → returns CDN URL.
cockpit_list_media	List a center's media library (reuse existing Bunny URLs).
cockpit_homepage_tiles	Read/create/change/delete homepage tiles.
cockpit_page_content	Read/write page content (hero, SEO, customContent) per pageType.
cockpit_revalidate_website	Manually invalidate website cache (usually automatic after push).

Drafts & approvals

Tool	What it does
cockpit_list_drafts	Open drafts — optionally includeData: true for payload like in Cockpit (customerCommunication, dispatchItemId, …). Includes createdByName.
cockpit_get_draft	A draft by ID — optionally includeData: true.
cockpit_update_draft	Approve or reject a draft.
cockpit_draft_customer_touchpoint	AI suggestion for customer communication (scenario like in workflow: approve / reject / pending).

Claude cannot find an MCP tool?

Claude.ai uses tool_search internally — with 70+ tools often only ~5 semantic hits are loaded. Specific tools like cockpit_audit_logs or cockpit_center_team may not appear, even though they are registered on the server.

Solution: Use cockpit_mcp_discover_tools with a keyword (audit, team, website, who changed, …) — returns the exact tool name. Then call the target tool directly. Alternatively, explicitly state the tool names in v0 instructions.

After deploying on Render: reconnect Remote-MCP to activate the new tool list.

---

Rule: Always _preview before _push. Claude does this automatically if you say "show me a preview first" in the prompt.

What	Possible?
Read Cockpit (shops, news, events, offers)	✅ always
Create new center	✅ always
Update center metadata	✅ always
Submit drafts for approval (submitToWorkflow)	✅ always
Approve drafts from Claude	✅ always
Read draft including data / customer contact from Claude	✅ cockpit_list_drafts / get_draft with includeData
Customer contact suggestion as in the dashboard	✅ cockpit_draft_customer_touchpoint
Audit: Who changed what when?	✅ cockpit_audit_logs (center or individual entry; summary for top authors)
Team: Who has access to a center?	✅ cockpit_center_team
Write directly to Cockpit (live, without approval)	⚠️ only if IT has activated COCKPIT_ALLOW_CONTENT_PUSH
Edit website code files	❌ not via MCP — use v0 or Build website with Claude
Social posts, approvals, engage, performance	❌ dashboard only → Social Cockpit
Content Planner (calendar, “online only” filter)	❌ dashboard only → /dashboard/content/planner
Dispatch (email inbox)	❌ dashboard only → Editorial flow
Social Outstand metrics (reach, followers)	❌ not via MCP — reporting in dashboard

---

Way B — Desktop App (Fallback · requires Node.js)

When Way B is useful

• You do not have Claude Pro/Team — only the free desktop app
• You want to work offline
• IT personnel sets it up once; the editor uses it thereafter

Setting up once (IT, once per Mac)

In the repo root folder:

pnpm install
pnpm mcp:init

The assistant will ask for:

• Dashboard URL (default https://dashboard.cockpit-os.de — keep it as is)
• AgencyOS API key (sk_agencyos_… — from IT/Cockpit settings → Integrations)
• Allow live push? (at the beginning: no recommended)

After that, completely exit and restart Claude Desktop. Done.

If the assistant aborts (entry already exists): COCKPIT_MCP_INIT_FORCE=1 pnpm mcp:init

Manually: pnpm --filter @mall-os/mcp-cockpit-os run build → Adjust claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\).

---

IT Setup: Set up Remote Server on Render

The Remote MCP service is already listed in render.yaml (mallos-mcp-cockpit). After a blueprint sync on Render, it runs automatically.

Set it manually only once after the first deploy on Render:

1. Render Dashboard → Service mallos-mcp-cockpit → Environment

2. COCKPIT_MCP_HTTP_BEARER — generate a long random secret:

   openssl rand -hex 32

   Enter this value in Render. Then assemble the finished connector URL for the editors:

   https://mallos-mcp-cockpit.onrender.com/mcp?token=<VALUE-FROM-RENDER>

   Transmit this URL securely (password manager, never in open chat or email).

3. COCKPIT_AGENCYOS_API_KEY — enter the AgencyOS API key (from Cockpit → Settings → Integrations → AgencyOS).

4. COCKPIT_ALLOW_CONTENT_PUSH — leave empty for a safe start (workflow mode only). Set to 1 if direct writing should be permitted.

5. Redeploy the service.

Health Check: https://mallos-mcp-cockpit.onrender.com/health — if {"status":"ok"} appears, everything is running.

Security Notes

• COCKPIT_MCP_HTTP_BEARER is the only secret between Claude and the MCP server. Whoever has it can access all MCP tools. If suspected of being shared: replace it immediately in Render with a new one and inform all editors.
• The secret must not appear in any chat, email, or public document.
• If direct writing is necessary: a separate Render instance with its own bearer for this user group is recommended.

---

AgencyOS API Key: Where to get it?

• Go to Cockpit Dashboard → Settings → API & Integrations (card AgencyOS – API Keys).
• Generate a new key — it always starts with sk_agencyos_. You will see the full key once in the dialog.
• Store it safely in a password manager, then enter it in Render.
• Read only (without key): The cockpit_public_* tools work without a key — useful for testing.

---

Problems?

Symptom	What to do
Connector does not appear / no tools in Claude	Is the URL correct? No / at the end? Reload the Claude page. In Claude Pro: check Settings → Connectors.
"401 Unauthorized"	Is the secret typed incorrectly? White spaces at the beginning/end? Is the Render variable set and service redeployed?
"503" or Timeout	Render Free Tier sleeps after inactivity — the first request may take 30 seconds. Just try again. Upgrade to the Starter Plan for always active.
"Push denied"	COCKPIT_ALLOW_CONTENT_PUSH not set — that's intentional. Workflow mode (submitToWorkflow: true) always works.
Desktop MCP: no tools visible	Is claude_desktop_config.json saved? Is the path to index.js correct? Has Claude been completely restarted (not just closed the window)?

---

Back to overview: Content Creator Handbook → Introduction