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.

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.

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.