Guides

Copy page

AI Agent Integration (MCP)

Connect AI agents like Claude, ChatGPT, and custom applications to the GoSmarter API using the Model Context Protocol (MCP) server.

What is MCP?

The Model Context Protocol (MCP) is a standardized way for AI agents to interact with APIs and resources. The GoSmarter MCP server provides:

• API Tools - All GoSmarter API operations available as callable tools
• Documentation Resources - Read-only access to product documentation
• Standardized Protocol - Works with any MCP-compatible AI agent
• Same Authentication - Uses your existing OAuth 2.0 credentials

Quick Start with Claude Desktop

The easiest way to get started is with Claude Desktop:

1. Install Claude Desktop

Download from claude.ai/download

2. Get Your Credentials

You'll need:

• OAuth 2.0 client ID and secret
• API gateway URL

Contact your administrator if you don't have these.

3. Get an Access Token

Code
 
curl --request POST \
  --url 'https://YOUR_TENANT.ciamlogin.com/YOUR_TENANT/oauth2/v2.0/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data scope=api://YOUR_API_ID/access_as_user

Save the access_token from the response.

4. Configure Claude Desktop

Edit the Claude Desktop config file:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Code
 
{
  "mcpServers": {
    "gosmarter": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-fetch",
        "https://YOUR_GATEWAY_URL.zuplo.app/mcp"
      ],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

5. Restart Claude Desktop

Claude will now have access to all GoSmarter API operations and documentation.

What Can AI Agents Do?

Once connected, AI agents can:

Call API Operations

Code
 
You: "Check the sync status for user ID abc-123"

Claude: I'll check that for you using the CheckUserSync tool.
[Calls CheckUserSync API with userId: "abc-123"]

The user sync status shows...

Access Documentation

Code
 
You: "How do I calculate scrap percentages?"

Claude: Let me check the documentation.
[Reads mcp://resources/docs/scrap-calculator/index]

According to the documentation, you can calculate scrap...

Perform Complex Workflows

Code
 
You: "Create an order for customer XYZ with 100 units of steel bar"

Claude: I'll help you create that order.
[Calls CreateOrder with appropriate parameters]

Order created successfully! Order ID: ORD-456...

Available Tools

The MCP server exposes all backend API operations as tools:

User Management

• CheckUserSync - Verify user synchronization status
• UpdateUser - Update user profile information

Inventory

• GetInventory - Retrieve inventory levels
• UpdateInventory - Modify inventory quantities

Orders

• CreateOrder - Create new customer orders
• UpdateOrder - Modify existing orders
• GetOrderStatus - Check order status

Scrap Calculation

• CalculateScrap - Calculate cutting scrap
• OptimizePattern - Find optimal cutting patterns

Mill Certificates

• UploadCertificate - Upload mill certificate
• GetCertificate - Retrieve certificate data

[See full list in the API Reference]

Available Documentation Resources

AI agents can read multiple documentation resources including:

• Dashboard usage guide
• FAQ and troubleshooting
• Getting started tutorials
• Glossary of terms
• Inventory management
• Mill certificates handling
• Optimization features
• Order management
• Quick reference guides
• Scrap calculator instructions
• General troubleshooting

Using MCP Programmatically

Python Example

Code
 
import requests
import os

class GoSmarterMCP:
    def __init__(self, gateway_url, access_token):
        self.url = f"{gateway_url}/mcp"
        self.headers = {
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json',
            'Accept': 'application/json, text/event-stream'
        }

    def list_tools(self):
        """List all available API tools"""
        response = requests.post(self.url, json={
            'jsonrpc': '2.0',
            'id': '1',
            'method': 'tools/list'
        }, headers=self.headers)

        return response.json()['result']['tools']

    def call_tool(self, tool_name, arguments):
        """Execute an API operation"""
        response = requests.post(self.url, json={
            'jsonrpc': '2.0',
            'id': '1',
            'method': 'tools/call',
            'params': {
                'name': tool_name,
                'arguments': arguments
            }
        }, headers=self.headers)

        return response.json()['result']

    def list_resources(self):
        """List all documentation resources"""
        response = requests.post(self.url, json={
            'jsonrpc': '2.0',
            'id': '1',
            'method': 'resources/list'
        }, headers=self.headers)

        return response.json()['result']['resources']

    def read_resource(self, uri):
        """Read a documentation resource"""
        response = requests.post(self.url, json={
            'jsonrpc': '2.0',
            'id': '1',
            'method': 'resources/read',
            'params': {'uri': uri}
        }, headers=self.headers)

        return response.json()['result']['contents'][0]['text']

# Usage
mcp = GoSmarterMCP(
    gateway_url='https://your-gateway.zuplo.app',
    access_token='your-access-token'
)

# List available tools
tools = mcp.list_tools()
print(f"Found {len(tools)} API operations")

# Call an API operation
result = mcp.call_tool('CheckUserSync', {
    'userId': 'abc-123'
})

# Read documentation
docs = mcp.read_resource('mcp://resources/docs/getting-started/index')
print(docs)

JavaScript Example

Code
 
class GoSmarterMCP {
  constructor(gatewayUrl, accessToken) {
    this.url = `${gatewayUrl}/mcp`;
    this.headers = {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      Accept: "application/json, text/event-stream",
    };
  }

  async listTools() {
    const response = await fetch(this.url, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "tools/list",
      }),
    });

    const data = await response.json();
    return data.result.tools;
  }

  async callTool(toolName, args) {
    const response = await fetch(this.url, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "tools/call",
        params: {
          name: toolName,
          arguments: args,
        },
      }),
    });

    const data = await response.json();
    return data.result;
  }

  async readResource(uri) {
    const response = await fetch(this.url, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({
        jsonrpc: "2.0",
        id: "1",
        method: "resources/read",
        params: { uri },
      }),
    });

    const data = await response.json();
    return data.result.contents[0].text;
  }
}

// Usage
const mcp = new GoSmarterMCP(
  "https://your-gateway.zuplo.app",
  "your-access-token"
);

// List and call tools
const tools = await mcp.listTools();
const result = await mcp.callTool("CheckUserSync", { userId: "abc-123" });

// Read documentation
const docs = await mcp.readResource(
  "mcp://resources/docs/getting-started/index"
);

MCP Protocol Reference

Request Format

All MCP requests use JSON-RPC 2.0:

Code
 
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method-name",
  "params": {
    // Method-specific parameters
  }
}

Response Format

Code
 
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // Method-specific result
  }
}

Error Format

Code
 
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

Authentication with MCP

MCP requests use the same OAuth 2.0 authentication as regular API calls:

Code
 
POST https://your-gateway.zuplo.app/mcp
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json, text/event-stream

Token Management for AI Agents

Since tokens expire after 1 hour:

1. For Interactive Use (Claude Desktop):

   • Generate a token before starting a session
   • Update the config file with the new token when it expires
   • Restart Claude Desktop after updating

2. For Programmatic Use:

   • Implement automatic token refresh (see Authentication guide)
   • Cache tokens and refresh proactively
   • Handle 401 errors by refreshing and retrying

Troubleshooting

406 Not Acceptable Error

Cause: Missing or incorrect Accept header

Solution: Always include:

Code
 
Accept: application/json, text/event-stream

401 Unauthorized

Cause: Token expired or invalid

Solution:

1. Generate a new access token
2. Update your configuration
3. Restart the AI agent/application

Tool Not Found

Cause: Tool name is incorrect

Solution:

1. List available tools using tools/list
2. Use the exact name field from the tool definition
3. Tool names are case-sensitive

Resource Not Found

Cause: Resource URI is incorrect

Solution:

1. List available resources using resources/list
2. Use the exact uri field from the resource definition
3. URI format is mcp://resources/docs/{path}

Best Practices

For AI Agents

• List tools first - Let the agent discover available operations
• Provide context - Give the agent relevant documentation resources
• Handle errors gracefully - Implement retry logic for network issues
• Cache tool lists - Don't list tools on every request

For Developers

• Implement token refresh - Automate token renewal
• Log requests - Track API usage and debug issues
• Validate responses - Check for errors before processing results
• Rate limit - Respect API rate limits (1000 req/hour)

Next Steps

• Authentication Guide - Learn about OAuth 2.0 and token management
• API Reference - Explore all available API operations
• Quick Start - Test the API directly before using MCP

Support

• Technical questions: [email protected]
• Report MCP issues: GitHub Issues
• Check service status: status.gosmarter.ai