Tillit Local MCP Server

A local Model Context Protocol (MCP) server for the Tillit API, built with @modelcontextprotocol/sdk. This server provides 195+ tools and 48+ resources for complete access to the Tillit manufacturing operations platform.

Quick Start

Using npx (Recommended)

TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret npx @gotillit/local-mcp-server

Using .env file (Recommended for Development)

Copy the example file and customize it:

cp .env.example .env

Then edit .env with your actual values:

TENANT=bottling
ENV_NAME=development
API_KEY=your-oauth2-client-id
SECRET=your-oauth2-client-secret

Then run:

npx @gotillit/local-mcp-server

Manual Installation

npm install -g @gotillit/local-mcp-server
TENANT=your-tenant ENV_NAME=development API_KEY=your-key SECRET=your-secret tillit-mcp-server

Environment Variables

Required

• TENANT - Your tenant name (e.g., "bottling", "manufacturing")
• ENV_NAME - Environment name (e.g., "development", "staging", "production")
• API_KEY - OAuth2 client ID for token authentication
• SECRET - OAuth2 client secret for token authentication

URL Construction

The server automatically constructs URLs using the format:

API Gateway URL:

• Development: https://{TENANT}.development.tillit-dev.cloud/api
• Other environments: https://{TENANT}.tillit-{ENV_NAME}.cloud/api

OAuth2 Token URL:

• Development: https://{TENANT}.development.tillit-dev.cloud/oauth2/token
• Other environments: https://{TENANT}.tillit-{ENV_NAME}.cloud/oauth2/token

Examples:

• TENANT=bottling + ENV_NAME=development →
  • API: https://bottling.development.tillit-dev.cloud/api
  • Auth: https://bottling.development.tillit-dev.cloud/oauth2/token

Claude Desktop Integration

Add this configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "tillit": {
      "command": "npx",
      "args": ["@gotillit/local-mcp-server"],
      "env": {
        "TENANT": "bottling",
        "ENV_NAME": "development",
        "API_KEY": "your-api-key",
        "SECRET": "your-secret",
        "REGION": "ap-southeast"
      }
    }
  }
}

Alternatively, if you have a .env file in the package directory, you can use a simpler configuration:

{
  "mcpServers": {
    "tillit": {
      "command": "npx",
      "args": ["@gotillit/local-mcp-server"]
    }
  }
}

Features

195+ API Tools

The server automatically provides tools for all Tillit API operations:

• Search: 4 tools for finding assets, orders, materials, and activities
• Asset Management: 12 tools for creating, updating, and managing assets
• Material Management: 41 tools for materials, groups, tolerances, movements, and conversions
• Order Management: 49 tools for orders, instances, templates, components, and attributes
• Activity Management: 89 tools for templates, instances, assignments, reporting, and image handling

48+ Resources

Access structured information about different API categories:

• tillit://Search - Search operations
• tillit://Assets - Asset management
• tillit://Materials - Material operations
• tillit://Orders - Order management
• tillit://Activities - Activity workflows
• And 43+ more categories...

📚 Built-in Documentation

The server includes comprehensive documentation resources accessible through MCP:

• tillit://documentation/overview - Complete usage guide with common patterns
• tillit://documentation/search - Search tools documentation
• tillit://documentation/assets - Asset management tools
• tillit://documentation/materials - Material handling tools
• tillit://documentation/orders - Production order tools
• tillit://documentation/activities - Workflow management tools

Each documentation resource provides:

• Usage guidance and best practices
• Complete tool inventory with descriptions
• Detailed parameter specifications
• Schema information for request bodies
• Common workflow patterns

Authentication

The server uses OAuth2 Client Credentials Grant for authentication:

OAuth2 Authentication

The server automatically manages OAuth2 tokens using your client credentials:

TENANT=bottling ENV_NAME=development API_KEY=your-client-id SECRET=your-client-secret npx @gotillit/local-mcp-server

The authentication flow:

1. Requests access token from Cognito using client credentials
2. Automatically refreshes tokens when they expire
3. Handles 401 responses by refreshing tokens
4. Uses Bearer token authentication for all API calls

Tenant Context

The TENANT environment variable is automatically added as a header:

tillit-tenant: bottling

Example Usage

Once connected to an MCP client (like Claude Desktop), you can:

Access Documentation

Read the "tillit://documentation/overview" resource to get started with usage patterns

List Available Tools

The client will automatically discover all 195+ available tools organized by category.

Execute API Operations

Use the "getAllAssets" tool to get all assets
Use the "getActiveActivities" tool to see available work
Use the "search" tool to find assets containing "motor" in their name

Work with Activities

Use "getActiveActivities" to see available work
Use "claimActivity" to assign work to yourself
Use "submitActivity" when work is complete

Access Resources by Category

Read the "tillit://Activities" resource to see all activity-related operations
Read the "tillit://Materials" resource to see all material management tools

Troubleshooting

Server Won't Start

• Verify all required environment variables are set: TENANT, ENV_NAME, API_KEY, SECRET
• Check Node.js version (requires Node 18+)
• Ensure network connectivity to your Tillit API
• Verify the constructed URLs are accessible

Authentication Errors

• Verify API_KEY (client ID) and SECRET (client secret) are correct OAuth2 credentials
• Check that your OAuth2 client has the required permissions
• Ensure the tenant name matches your account setup
• Verify the constructed OAuth2 token URL is accessible

Tool Execution Failures

• Check that your OAuth2 client has the required permissions for the specific operations
• Verify the target API endpoint is accessible
• Review the tool parameters match the API requirements
• Check the server logs for detailed error messages

Environment Variable Issues

• Environment variables from the shell take precedence over .env file values
• The .env file is only loaded if required variables are missing from the environment
• Check for typos in variable names (case-sensitive)
• Ensure the .env file is in the correct location if using file-based configuration

Development

Local Development Setup

git clone <repository-url>
cd tillit-sdk/clients/tillit-mcp/local
npm install
npm run build
node src/index.js

Building from Source

The build process copies the latest MCP tools and resources:

npm run build

Running Tests

npm run test:all      # Run all tests
npm run test:oauth2   # Test OAuth2 authentication
npm run test:docs     # Test documentation loading

Technical Details

• Runtime: Node.js 18+
• Protocol: MCP over stdio transport
• Authentication: OAuth2 Client Credentials Grant with automatic token management
• Dependencies: @modelcontextprotocol/sdk, axios, dotenv
• Architecture: ES modules with comprehensive error handling and logging

API Coverage

The server provides access to these Tillit API areas:

• /core/search - Universal search capabilities
• /core/assets/* - Asset management operations
• /core/materials/* - Material handling and inventory
• /core/material-* - Material groups, tolerances, conversions
• /core/orders/* - Order management and tracking
• /core/order-* - Order instances, templates, components
• /activity/* - Complete activity workflow management

Support

For issues, questions, or feature requests, please contact the Tillit team or refer to the main project documentation.

License

Apache-2.0