MCP Server masamenu.tr — API & Tool Integration Reference

This document is intended for AI assistants, GPT bots, and automated integrations. It contains precise protocol details, tool schemas, and the authentication flow.

Server information#

Authentication#

All tool calls require the Authorization header. The address above is an example for masamenu.tr; on another brand, use the URL from your own panel. Bucket names in tools/list schemas are also selected by the request brand.

Option 1: User MCP API key (recommended)#

Authorization: Bearer XXXXXXXXXXXX...  (64 hex characters, no prefix)

The key is tied to one user. The bot can see only that user's data.

The mk_… value shown in the admin panel's key list is the key ID (used in DELETE /api/keys/{keyId}), not the key itself.

Option 2: Cognito JWT token#

Authorization: Bearer eyJraWQi...  (JWT id_token)

Obtain it with POST /auth/login. It expires after 1 hour.

Option 3: Admin API key#

Authorization: Bearer <admin_api_key>

Full access to all data. Administrators only.

Obtaining a JWT token#

POST https://api.masamenu.tr/mcp/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "idToken": "eyJraWQi...",
  "accessToken": "eyJraWQi...",
  "refreshToken": "eyJjdHki...",
  "expiresIn": 3600,
  "tokenType": "Bearer"
}

MCP protocol#

Initialization#

POST https://api.masamenu.tr/mcp
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-bot", "version": "1.0" }
  }
}

Tool list#

{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }

Calling a tool#

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "имя_инструмента",
    "arguments": { ... }
  }
}

Success response: result.content[0].text is a JSON string containing the data.
Error response: result.isError: true; result.content[0].text contains the error text.

Endpoints#

/api/keys is authorized as the user: either a Cognito JWT or that user's own 64-character MCP key works. An admin key does not work because it has no user binding; the response is 403 user identity required.

All paths are relative to https://api.masamenu.tr/mcp.

Complete tool reference#

Access levels#

• USER — Operations on behalf of an authenticated user; order-isolation limitations are described below
• ADMIN — Administrators only (full access)

Self-service#

User profiles#

Locations#

update_location_profile fields that can be updated: displayName, phone, address, facebookUrl, instagramUrl, status, settings, workingHours. The CDN is synchronized automatically. Use set_location_domain to change the domain.

Menu#

check_translations scans every category and dish in the location, finds missing translations for enabled languages, and returns a detailed language report listing categories and dishes without translations.

Application languages#

Allowed codes: ka, en, ru, tr, hy, zh, hi, es, fr, ar, bn, pt, id, ur, de, ja, ko, vi, it, pl, uk, fa, he, az, kk, uz, ab, sq, sr, mk, bg, ro, el, nl, mt, sv, no, da, fi, cs, hu, hr, lt, th, ms.

Working hours#

Days not specified in set_working_hours remain unchanged. Calling add_schedule_exception again for the same date replaces the existing exception.

update_menu_item fields that can be updated: name, description, price, status, tags, variantGroups, addons, nameTranslations, descriptionTranslations, locationPrices, sortOrder. The CDN is synchronized automatically.

Orders#

Domains#

CDN#

Images#

get_image_upload_url returns a presigned URL (15 minutes). After upload, the pipeline automatically generates thumbnails and synchronizes them with the CDN.

S3 storage#

Bucket enum: data.meni, cdn.masamenu.tr, i.masamenu.tr, o.masamenu.tr.

Cognito#

System#

Access control#

1. Profile and self-service tools use the regular user’s own userId
2. Low-level access to data and image buckets is restricted to the users/{userId}/ prefix; published CDN data is read by domain
3. For location/menu tools, userId is auto-detected for regular users (only admins provide it)
4. Admin-only: list_users, search_user_by_email, list_domains, invalidate_cdn_cache, s3_write, s3_delete, cognito_list_users, cognito_get_user, get_system_stats
5. update_user_profile is also available to regular users: the schema requires userId, but for non-admins the server always substitutes their own identifier, so the tool cannot change another user's profile
6. Key management (/api/keys) requires user-bound authorization: a Cognito JWT or the user's own MCP key (an admin key is not accepted)

Known access-control limitation: server-side domain ownership checks for reading orders are incomplete. Do not treat the USER role as a complete isolation boundary for untrusted integrations. Connect only trusted applications; see the API reference.

Error codes#

Example session#

→ POST /  {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"bot","version":"1.0"}}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"meni-user-data","version":"1.0.0"}}}

→ POST /  {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"whoami","arguments":{}}}
← {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"userId\":\"abc-123\",\"email\":\"user@example.com\"}"}]}}

Client configuration#

Claude Desktop#

{
  "mcpServers": {
    "meni": {
      "url": "https://api.masamenu.tr/mcp",
      "headers": { "Authorization": "Bearer <API_KEY>" }
    }
  }
}

cURL#

curl -X POST https://api.masamenu.tr/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'