MCP Service - Getting Started

What is the StockIQ MCP Server?

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call tools in another system. The StockIQ MCP server exposes StockIQ's own tools: forecasts, inventory, order suggestions, alerts, executive summaries and more — so an assistant such as Claude, Codex or Cursor can answer questions about your StockIQ data instead of guessing.

In practice, once it is connected you can ask your assistant things like:

• "Which suppliers are close to their order minimums this week?"
• "Show me the items at the Dallas site with the worst forecast error last quarter."
• "Explain why StockIQ suggested this purchase order."

NOTE: This article covers connecting an external AI client to StockIQ. It is not about Edison, the assistant built into the StockIQ web application. Edison is used by signed-in StockIQ users inside the product; the MCP server is used by outside tools authenticating with a token. The two reach the same underlying tools and obey the same permissions.

Before You Start

You will need all four of the following.

1. The MCP add-on on your StockIQ licence. If the MCP Tokens tab does not appear where this article says it should, your licence does not include it. Contact StockIQ Support or your account manager.
2. A StockIQ administrator — specifically, someone whose role grants the Administer MCP Tokens permission. This is who creates the token.
3. An MCP-capable client. Claude Code, OpenAI Codex CLI, Cursor, Continue.dev and VS Code (GitHub Copilot) are all supported and covered below.
4. Your StockIQ instance URL, for example https://contoso.stockiqtech.net. Your MCP endpoint is that address with /mcp on the end.

Network requirements

The connection is outbound only. Your client calls StockIQ over HTTPS on port 443, using the standard streamable HTTP MCP transport. No inbound firewall rule is needed, and StockIQ never initiates a connection back to your machine. There is also no separate long-lived event-stream connection to allow for — some older MCP material describes one, but the StockIQ endpoint does not use it.

If your organisation routes traffic through a forward proxy, the client must be able to reach your StockIQ instance address through it, and the proxy must not strip the Authorization header.

Step 1: Create an MCP Token

An MCP token is the credential your AI client presents to StockIQ. It is created by an administrator inside StockIQ.

1. Sign in to StockIQ and go to Admin → Manage Security.
2. Select the MCP Tokens tab.
3. Click Add.
4. Fill in the token details:
   • Name — a label you will recognise later, for example "Jane – Claude Code". This name is what appears in StockIQ's logs and change history, so make it specific. Names must be unique.
   • Description — optional free text; useful for recording who asked for it and why.
   • Expires — when the token stops being accepted. We strongly recommend setting one. Leave it blank only if you have a specific reason to create a token that never expires.
   • Roles — the roles that determine what the token may do. This is the single most important setting; see Give the token only the access it needs below.
   • Data scopes — optionally restrict the token to specific sites, suppliers, buyers, shippers or item categories, exactly as you would for a user.
5. Save. StockIQ displays the token — a long string beginning with eyJ.

IMPORTANT: The token is shown once, at the moment it is created. StockIQ stores only a one-way hash of it and cannot show it to you again. Copy it somewhere safe before closing the dialog. If you lose it, you must rotate the token to get a new one.

Give the token only the access it needs

A token's roles work exactly like a user's roles. A token assigned the Inventory Manager role can use the inventory tools; a token with no roles can connect but will find almost nothing available to it.

Grant the minimum that does the job. If the person is only asking questions about forecasts and inventory, a read-oriented role is enough — there is no need to grant order placement.

Step 2: Store the Token Safely

Treat the token like a password. Anyone holding it can act with the token's roles and data scopes until it expires or is revoked.

Do

• Store it in your operating system's secret store — Windows Credential Manager, macOS Keychain, or Linux Secret Service. Most MCP clients can either read from it directly or prompt you once and save it there.
• If your client can only read from the environment, set it in your shell profile and reference it as a variable, so the token never appears in the client's configuration file. The examples below all do this.
• Set an expiration. Ninety days is a sensible default.
• Use one token per person, per client. That keeps the "last used" timestamp meaningful and lets you revoke one client's access without disrupting anyone else.
• Rotate immediately if the token ever appears somewhere it should not — a screenshot, a chat message, a committed file.

Don't

• Don't commit the token to source control. If it must live in a file, add that file to .gitignore before you paste the token in.
• Don't paste it into support tickets, chat or screenshots. Refer to the token by its Name instead.
• Don't share one token between people or machines. That defeats the audit trail and means revoking it disrupts everyone.

Step 3: Connect Your Client

Every example below assumes you have put the token in an environment variable called STOCKIQ_MCP_TOKEN, and that your endpoint is https://contoso.stockiqtech.net/mcp. Substitute your own instance address.

Claude Code

Add the server from the command line:

claude mcp add stockiq --transport http https://contoso.stockiqtech.net/mcp \
    --header "Authorization: Bearer $STOCKIQ_MCP_TOKEN"

• Add --scope user to share the configuration across all your projects; omit it for the current project only.
• The MCP process inherits the environment when it launches, so set STOCKIQ_MCP_TOKEN before starting Claude Code.
• Check it worked with claude mcp list, then type /mcp inside a session.

OpenAI Codex CLI

Add an HTTP MCP server block to ~/.codex/config.toml:

[mcp_servers.stockiq]
type = "http"
url  = "https://contoso.stockiqtech.net/mcp"

[mcp_servers.stockiq.headers]
Authorization = "Bearer ${STOCKIQ_MCP_TOKEN}"

Codex resolves ${VAR} from your shell environment, so the token stays out of the file. Restart the Codex session after editing the configuration.

Cursor

Go to Settings → Features → Model Context Protocol → Add new server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "stockiq": {
      "type": "http",
      "url": "https://contoso.stockiqtech.net/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STOCKIQ_MCP_TOKEN}"
      }
    }
  }
}

Continue.dev

Add a server entry to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "stockiq",
      "transport": {
        "type": "http",
        "url": "https://contoso.stockiqtech.net/mcp",
        "headers": { "Authorization": "Bearer ${STOCKIQ_MCP_TOKEN}" }
      }
    }
  ]
}

VS Code (GitHub Copilot)

Use the command palette → MCP: Add Server, or edit .vscode/mcp.json:

{
  "servers": {
    "stockiq": {
      "type": "http",
      "url": "https://contoso.stockiqtech.net/mcp",
      "headers": {
        "Authorization": "Bearer ${input:stockiq-mcp-token}"
      }
    }
  },
  "inputs": [
    {
      "id": "stockiq-mcp-token",
      "type": "promptString",
      "password": true,
      "description": "StockIQ MCP token"
    }
  ]
}

The inputs block prompts you once and stores the token in your operating system's secret store, so it never ends up in mcp.json.

Step 4: Verify the Connection

Ask your client to list its MCP tools. You should see StockIQ tools such as ShowCapabilities and GetInstanceInfo.

A good first question to your assistant is simply:

What StockIQ tools do you have available, and what can you tell me about this instance?

If the assistant answers with your instance details, you are connected.

Where Your Data Goes

Worth understanding before you go further, because it is the question your security team will ask.

When your assistant calls a StockIQ tool, StockIQ returns the result to your AI client — Claude Code, Cursor, Codex or whichever you connected. That client then sends the result on to the AI provider it is configured to use, so it can be turned into an answer. StockIQ does not choose that provider and has no relationship with it, so the boundary is under your control rather than ours: you decide which provider sees the data by choosing the client, and you decide how much data can reach it through the token's roles and data scopes.

NOTE: Edison inside the StockIQ web application is different. There, StockIQ runs the model under its own agreement and no third party of your choosing is involved. If your policy does not permit StockIQ data to reach an external AI provider, Edison is the option that keeps it inside StockIQ.

See MCP Service — Security and Data Handling for the full data-flow description, what StockIQ records, and the shared-responsibility split. That article is written to be read by a security reviewer before any token is created.

What an MCP Token Can and Cannot Do

An MCP token is a program acting for your organisation — not a stand-in for a person. That distinction drives the following deliberate limits, which apply no matter which roles you grant.

NOTE: If a tool is refused, StockIQ tells your assistant why in plain language, including which permission is missing and whether retrying could help. Ask your assistant to repeat the message verbatim, then pass it to your administrator.

Monitoring and Auditing Token Activity

Everything an MCP token does is recorded. Three places to look:

• Admin → Manage Security → MCP Tokens shows each token's Last Used timestamp — the quickest way to spot a token nobody needs any more.
• Admin → Usage Log shows every request the token made, listed under the token's Name rather than a user name, so integration traffic is easy to tell apart from people.
• Admin → Audit Trail shows every change a token made, with the old and new value of each field, filterable by caller type, record type, item site and date. Records here are kept far longer than the usage log.

Because changes are attributed to the token by name, you can always answer "which of our integrations changed this setting, and what was it before?"

Rotating and Revoking a Token

From Admin → Manage Security → MCP Tokens:

• Rotate issues a replacement token and invalidates the old one immediately. Any client still presenting the previous token receives an authentication error on its next call. Use this if a token may have been exposed, or if it was lost.
• Delete deactivates the token permanently. Its history in the Usage Log and Audit Trail is retained — revoking a token never erases the record of what it did.

Troubleshooting

Getting Help

If you get stuck, contact StockIQ Support and include:

1. The Name of the MCP token — never the token value itself.
2. Which client you are connecting from, and its version.
3. The exact error message your client displayed.
4. Roughly when you tried, so we can match it against the Usage Log.

Rate limits

MCP traffic is rate limited so that one client cannot slow your instance down for everyone else. Limits are counted per MCP token, and the figures below are the defaults. They can be raised for an individual instance — if a client legitimately needs more headroom, contact support@stockiqtech.com.

The throughput limit works as an allowance that refills rather than a quota that resets. It holds up to 20 requests' worth of credit and is topped up by 10 every minute, so a client that has been idle can issue 20 requests straight away and then settles to a sustained 10 a minute. The top-up arrives as a single batch of 10 each minute, not as a trickle — after a burst, expect to wait rather than to speed up gradually.

NOTE: Both of those limits count every request to the MCP endpoint, not only tool calls. The initial handshake and each refresh of the tool list are requests too, so a client that reconnects frequently spends part of its allowance on reconnecting.

Write tools are the ones that change data on your behalf — for example PlaceOrder, ActivateInactiveRecords, SaveSafetyStockOverride, SaveOrderPolicyOverrides and SetSetting. They are held to 5 a minute in addition to the limits above: a write also consumes one request from the ordinary allowance. Read-only tools are subject only to the limits above.

What a rate-limited response looks like

Exceeding either of the first two limits is rejected with 429 Too Many Requests and a JSON-RPC error, code -32029:

HTTP/1.1 429 Too Many Requests

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32029,
    "message": "Too many requests. Please wait and retry."
  },
  "id": null
}

No Retry-After header is sent with these. If you were rejected for having too many requests in flight, retry as soon as one of them finishes; if you exhausted the throughput allowance, wait up to a minute for the next top-up.

IMPORTANT: The write limit reports itself differently, and a client that inspects only HTTP status codes will miss it. The request succeeds at the protocol level — 200 OK — and the refusal is returned inside the tool's own result:

{
  "error": "rate_limit_exceeded",
  "message": "Write operation rate limit exceeded. Maximum 5 write operations per minute per token.",
  "retryAfterSeconds": 60
}

Nothing was written. An AI assistant driving the session will normally read that message and back off by itself. A custom client must treat a tool result containing "error": "rate_limit_exceeded" as "retry later", never as a completed write — and must not report success to the user on the strength of the 200.

Staying under the limits

• Work through tool calls in sequence. Three requests in flight is the ceiling, and a fourth is refused outright rather than queued, so fanning calls out in parallel costs more than it saves.
• Filter broadly in one call instead of looping. Most StockIQ tools accept lists of items, sites, or suppliers. One call covering fifty items uses one request; fifty calls use fifty, and exhaust the allowance five times over.
• Batch writes where the tool allows it. Placing one order covering many lines costs one write against the limit of 5; placing them line by line does not.
• Give each client its own MCP token. Allowances are counted per token, so two clients on separate tokens never compete for the same one.

NOTE: These limits apply only to external MCP clients connecting with an MCP token. Edison inside the StockIQ web application does not use them, so a user chatting with Edison never consumes your client's allowance, and your client never slows Edison down.