Integrating Shifts MCP with Claude

This guide explains how to use Claude to interact with the Shifts API through the Message Control Protocol (MCP) endpoint.

Setup Options

You can integrate with the Shifts API using either user-based tokens or service account tokens, depending on your security needs.

Option 1: User Token Integration

This approach uses a standard user-level API token for authentication.

{
  "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"
  }
}

Option 2: Service Account Integration (Recommended for System Integration)

This approach uses service account tokens with secrets for enhanced security.

{
  "model": "claude-3-opus-20240229",
  "messages": [
    {"role": "user", "content": "Show me all shifts scheduled for tomorrow at the Main Store location"}
  ],
  "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-service-account-token",
    "additional_headers": {
      "X-API-Secret": "your-service-account-secret"
    }
  }
}

Available Tools

The following tools are available for use with the MCP endpoint:

Token Management

Obtaining Tokens

1. Navigate to the API Tokens page in the admin dashboard
2. Choose between creating a user token or service account token
3. For service account tokens, select the appropriate permission scopes
4. Copy and securely store the token (and secret for service accounts)

Token Security

• Never embed tokens directly in client-side code
• Use a secure backend server to make API calls
• Store tokens in environment variables or a secure secrets manager
• Rotate tokens periodically (recommended every 6-12 months)
• Use service account tokens with minimum required scopes for enhanced security

Example Node.js Implementation

Here’s a simple Node.js implementation for making MCP requests with service account authentication:

const axios = require('axios');

async function makeShiftsMcpRequest(toolName, input) {
  try {
    const response = await axios.post(
      'https://your-shifts-app.com/api/v1/mcp',
      {
        type: 'tool_use',
        tool_name: toolName,
        input: input
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.SHIFTS_API_TOKEN}`,
          'X-API-Secret': process.env.SHIFTS_API_SECRET,
          'Content-Type': 'application/json'
        }
      }
    );
    
    return response.data;
  } catch (error) {
    console.error('MCP request failed:', error.response?.data || error.message);
    throw error;
  }
}

// Example usage
async function getTomorrowShifts() {
  const tomorrow = new Date();
  tomorrow.setDate(tomorrow.getDate() + 1);
  const formattedDate = tomorrow.toISOString().split('T')[0];
  
  const result = await makeShiftsMcpRequest('get_shifts', { date: formattedDate });
  return result;
}

Troubleshooting

Common Issues

1. Authentication Failures
   • Verify that your token and secret (for service accounts) are correct
   • Check that the token has not expired
   • Ensure the token has the required scopes for the tools you’re using
2. MCP Request Failures
   • Validate that your request follows the correct MCP format
   • Check the API logs in the admin dashboard for specific error details
   • Verify that your input parameters match the expected schema

For additional help, contact Shifts support or refer to the full API documentation.