Guides

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 standardised 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
Standardised Protocol — Works with any MCP-compatible AI agent
Flexible Auth — API keys for automation; Bearer tokens for user-delegated access

Authentication for AI Agents

Option 1: API key (recommended for scripts and custom agents)

API keys don't expire and need no token refresh logic — the right choice for AI agents, automation scripts, and long-running integrations.

Code
POST https://api.gosmarter.ai/mcp
GoSmarter-Api-Key: zpka_your_key_here
Content-Type: application/json
Accept: application/json, text/event-stream

Get a key from My Account → API Keys in this portal. See the API Keys guide for rotation and revocation.

Option 2: Bearer token (user-delegated access or Claude Desktop)

Use when the agent must act on behalf of a specific user, or when using a standard MCP host like Claude Desktop that only supports the Authorization: header.

Code
POST https://api.gosmarter.ai/mcp
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
Accept: application/json, text/event-stream

Tokens expire after 1 hour — see Authentication for token acquisition and caching.

Quick Start with Claude Desktop

Claude Desktop uses @modelcontextprotocol/server-fetch, which only sends the Authorization: header. Use a Bearer token for this setup.

1. Install Claude Desktop

Download from claude.ai/download

2. Get a Bearer token

Code
curl --request POST \
  --url 'https://36078520-1cde-40ad-940e-6f26f1a90414.ciamlogin.com/36078520-1cde-40ad-940e-6f26f1a90414/oauth2/v2.0/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'scope=api://0399c3db-81cb-4a1e-8ff6-9fcfca8dec21/access_as_user'

Contact your GoSmarter administrator for client credentials if you don't have them.

3. 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://api.gosmarter.ai/mcp"
      ],
      "env": {
        "AUTHORIZATION": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

4. Restart Claude Desktop

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

Quick Start with a Custom Agent (API key)

For programmatic agents and scripts, use an API key — no token acquisition or refresh required.

Python


Code
import requests
import os

MCP_URL = "https://api.gosmarter.ai/mcp"
HEADERS = {
    "GoSmarter-Api-Key": os.environ["GOSMARTER_API_KEY"],
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
}

def list_tools():
    resp = requests.post(MCP_URL, json={
        "jsonrpc": "2.0", "id": "1", "method": "tools/list"
    }, headers=HEADERS)
    return resp.json()["result"]["tools"]

def call_tool(tool_name, arguments):
    resp = requests.post(MCP_URL, json={
        "jsonrpc": "2.0", "id": "1",
        "method": "tools/call",
        "params": {"name": tool_name, "arguments": arguments},
    }, headers=HEADERS)
    return resp.json()["result"]

def read_resource(uri):
    resp = requests.post(MCP_URL, json={
        "jsonrpc": "2.0", "id": "1",
        "method": "resources/read",
        "params": {"uri": uri},
    }, headers=HEADERS)
    return resp.json()["result"]["contents"][0]["text"]

JavaScript / Node.js


Code
const MCP_URL = "https://api.gosmarter.ai/mcp";
const headers = {
  "GoSmarter-Api-Key": process.env.GOSMARTER_API_KEY,
  "Content-Type": "application/json",
  "Accept": "application/json, text/event-stream",
};

async function listTools() {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({ jsonrpc: "2.0", id: "1", method: "tools/list" }),
  });
  return (await res.json()).result.tools;
}

async function callTool(toolName, args) {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
      jsonrpc: "2.0", id: "1",
      method: "tools/call",
      params: { name: toolName, arguments: args },
    }),
  });
  return (await res.json()).result;
}

async function readResource(uri) {
  const res = await fetch(MCP_URL, {
    method: "POST",
    headers,
    body: JSON.stringify({
      jsonrpc: "2.0", id: "1",
      method: "resources/read",
      params: { uri },
    }),
  });
  return (await res.json()).result.contents[0].text;
}

What Can AI Agents Do?

Once connected, AI agents can:

Perform 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. See the full list in the API Reference.

Available Documentation Resources

AI agents can read multiple documentation resources including dashboard usage, FAQ, getting started tutorials, glossary, inventory management, mill certificates, optimisation, order management, quick reference, scrap calculator, and troubleshooting guides.

MCP Protocol Reference

All MCP requests use JSON-RPC 2.0:


Code
{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "method-name",
  "params": {}
}

Always include Accept: application/json, text/event-stream — some transports require it.

Key Management for AI Agents

API key (recommended)

No expiry — no refresh logic needed
Rotate via Settings → API Keys → Roll in this portal
Delete immediately if compromised
Store in environment variables or a secrets manager — never in source code

Bearer token

Expires after 1 hour — implement token caching and proactive refresh
See Authentication for caching patterns

Troubleshooting

406 Not Acceptable

Cause: Missing Accept header. Fix: Always include Accept: application/json, text/event-stream.

401 Unauthorized (API key)

Verify the key is valid: Settings → API Keys in this portal
Check the header name is exact: GoSmarter-Api-Key
If the key was created before user metadata was populated, delete and recreate it

401 Unauthorized (Bearer token)

Token has expired — request a new one
Verify scope=api://0399c3db-81cb-4a1e-8ff6-9fcfca8dec21/access_as_user is included

Tool Not Found

List available tools first: tools/list. Tool names are case-sensitive.

Resource Not Found

List available resources first: resources/list. URI format: mcp://resources/docs/{path}.

Best Practices

Prefer API keys for agent integrations — no token expiry to manage
List tools once at startup — don't list on every request
Handle errors gracefully — implement retry logic for transient network issues
Cache tool lists — the available tools don't change between requests
Respect rate limits — 1000 req/hour

Next Steps

API Keys — Create, rotate, and revoke API keys
Authentication — OAuth 2.0 and Bearer token details
Quick Start — Test the API directly before using MCP
API Reference — Explore all available operations

Support

Technical questions: [email protected]

Last modified on July 21, 2026

API Keys