GoSmarter Logo
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

TerminalCode
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

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

JavascriptCode
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:

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

Support

Last modified on
API KeysVersioning Policy