Shifts MCP Endpoint Documentation

This document describes the Anthropic Message Control Protocol (MCP) endpoint provided by the Shifts application.

Endpoint URL

POST https://your-shifts-app.com/api/v1/mcp

Authentication

The MCP endpoint supports two types of authentication:

1. User API Tokens

For tokens associated with a specific user:

Authorization: Bearer your-api-token

2. Service Account Tokens

For service-to-service integrations that require additional security:

Authorization: Bearer your-token
X-API-Secret: your-secret-key

Service account tokens can have specific permission scopes and don’t require a user to be logged in. This is ideal for machine-to-machine communication.

For internal API calls, you can also use:

X-Internal-API: true
Authorization: Bearer internal_api_key

Service Account Scopes

Service account tokens can be limited to specific permissions using scopes:

Scope Description read:shifts View shift information write:shifts Create and modify shifts read:leave_requests View leave requests write:leave_requests Create and modify leave requests read:users View user profiles write:users Modify user information admin Full access to all endpoints

Protocol Format

The Anthropic MCP protocol uses a standard format for requests and responses:

Request Format (tool_use)

{
  "type": "tool_use",
  "tool_name": "get_shifts",
  "input": {
    "user_id": 123,
    "date": "2025-04-10"
  }
}

Response Format (tool_result)

{
  "type": "tool_result",
  "tool_name": "get_shifts",
  "content": {
    "shifts": [
      {
        "id": 456,
        "name": "Morning Shift",
        "start_time": "2025-04-10T08:00:00Z",
        "end_time": "2025-04-10T16:00:00Z",
        "location": "Main Store",
        "users": [{"id": 123, "name": "John Doe"}],
        "status": "scheduled"
      }
    ],
    "count": 1
  }
}

Available Tools

get_shifts

Get shifts for specified users and dates.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "description": "Filter shifts for a specific user (optional)"
    },
    "date": {
      "type": "string",
      "format": "date",
      "description": "Filter shifts for a specific date (YYYY-MM-DD, optional)"
    }
  }
}

get_leave_requests

Get leave requests with optional filters.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "description": "Filter leave requests for a specific user (optional)"
    },
    "status": {
      "type": "string",
      "enum": ["pending", "approved", "denied", "cancelled"],
      "description": "Filter by status (optional)"
    }
  }
}

create_leave_request

Create a new leave request.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "description": "User ID for the leave request (defaults to current user if omitted)"
    },
    "leave_type_id": {
      "type": "integer",
      "description": "ID of the leave type"
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Start date of leave (YYYY-MM-DD)"
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "End date of leave (YYYY-MM-DD)"
    },
    "notes": {
      "type": "string",
      "description": "Optional notes for the leave request"
    }
  },
  "required": ["leave_type_id", "start_date", "end_date"]
}

verify_phone

Send a verification code to the specified phone number.

Input Schema:

{
  "type": "object",
  "properties": {
    "phone": {
      "type": "string",
      "description": "Phone number to verify"
    },
    "user_id": {
      "type": "integer",
      "description": "User ID (defaults to current user if omitted)"
    }
  },
  "required": ["phone"]
}

get_user_profile

Get a user’s profile information.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "description": "User ID (defaults to current user if omitted)"
    }
  }
}

get_leave_balances

Get a user’s leave balances for the current year.

Input Schema:

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "integer",
      "description": "User ID (defaults to current user if omitted)"
    }
  }
}

Using with Claude

To use this MCP endpoint with Claude, you’ll need to define the tools and provide the MCP endpoint URL when making a request to Claude’s API:

{
  "model": "claude-3-opus-20240229",
  "messages": [
    {"role": "user", "content": "Show me my upcoming shifts for next week"}
  ],
  "tools": [
    {
      "name": "get_shifts",
      "description": "Get shifts for a specific user on a given date",
      "input_schema": {
        "type": "object",
        "properties": {
          "user_id": {
            "type": "integer",
            "description": "The ID of the user"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "The date to get shifts for (YYYY-MM-DD)"
          }
        }
      }
    }
  ],
  "tool_choice": "auto",
  "mcp_endpoint": "https://your-shifts-app.com/api/v1/mcp",
  "authentication": {
    "type": "bearer",
    "authorization_header": "Bearer your-api-token-here"
  }
}

Error Handling

The MCP endpoint returns error information in the standard format:

{
  "type": "tool_result",
  "tool_name": "get_shifts",
  "content": {
    "error": "Error message details"
  }
}