Zudello MCP Server

MCP server for Zudello API integration. Supports MCP 2025-03-26 Streamable HTTP standard with both stateful (session-based) and stateless operation modes.

Features

• Stdio Mode: Traditional MCP transport for direct client integration
• HTTP Mode: Streamable HTTP transport (MCP 2025-03-26) with session management
• Header Authentication: Secure authentication via HTTP headers
• Stateless Support: Each request carries its own authentication context
• Streaming: Automatic upgrade to Server-Sent Events for large result sets (>5 items)
• Session Management: 30-minute session timeout with automatic cleanup

Configuration

Create a .env file or set environment variables:

ZUDELLO_API_URL=https://api.au.3.zudello.io
ZUDELLO_AUTH_TOKEN=your_auth_token_here
ZUDELLO_ORGANIZATION_UUID=your_organization_uuid_here
ZUDELLO_TEAM_UUID=your_team_uuid_here

Usage

Claude Configuration

Add to your Claude MCP settings:

{
  "mcpServers": {
    "zudello": {
      "command": "npx",
      "args": ["@zudello_private/zudello-mcp", "--stdio"],
      "env": {
        "ZUDELLO_API_URL": "https://api.au.3.zudello.io",
        "ZUDELLO_AUTH_TOKEN": "your_auth_token_here",
        "ZUDELLO_ORGANIZATION_UUID": "your_organization_uuid_here",
        "ZUDELLO_TEAM_UUID": "your_team_uuid_here"
      }
    }
  }
}

HTTP Server

Runs on port 3001 with endpoints:

• /mcp - MCP 2025-03-26 Streamable HTTP endpoint
• /health - Health check and server info

Authentication

HTTP mode uses header-based authentication for security:

Authorization: Bearer <your-auth-token>
X-API-URL: https://api.au.3.zudello.io
X-Organization: <organization-uuid>
X-Team: <team-uuid>

Example request:

curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-API-URL: https://api.au.3.zudello.io" \
  -H "X-Organization: your-org-uuid" \
  -H "X-Team: your-team-uuid" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search-resources",
      "arguments": {
        "model": "Item",
        "limit": 10
      }
    }
  }'

Development

# Test with MCP Inspector
npm run test:stdio

# Build
npm run build

# Start HTTP server (default)
npm start

# Start stdio server
npm run start:stdio

# Publish
npm publish

Railway Deployment

Prerequisites

1. A Railway account and project
2. Railway CLI installed (optional)

Deployment Steps

1. Set Environment Variables in Railway:

   PORT=3001
   CORS_ORIGIN=https://your-app.com
   NODE_ENV=production

   Note: Do NOT set sensitive variables like auth tokens in Railway. These should be passed via headers in each request.

2. Deploy using Railway CLI:

   railway link
   railway up

   Or deploy via GitHub integration in Railway dashboard.

3. Verify Deployment:

   curl https://your-app.railway.app/health

Security Considerations

• Always use HTTPS in production (Railway provides this)
• Set CORS_ORIGIN to specific domains, not *
• Consider implementing rate limiting
• Monitor usage and set up alerts
• Use Railway's private networking for internal services

Testing the Deployed Server

# Test with authentication headers
curl -X POST https://your-app.railway.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -H "X-API-URL: https://api.au.3.zudello.io" \
  -H "X-Organization: your-org-uuid" \
  -H "X-Team: your-team-uuid" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'