Agent connection guide

Connect an agent to the shelf.

Connect an agent to four read-only MCP tools for the retail observations your organization already owns. The organization key also authorizes the broader machine API, including write routes, so keep it in a trusted workspace.

Start with an API key

Connection contract

Live
https://mcp.aisletrace.com/mcp
Transport
Streamable HTTP
Authorization
Bearer organization key
Access
MCP: read-only · 4 tools
01

Create the credential

Sign in and create an organization API key.

Open API keys in Aisle Trace, name the client, and create the key. The active organization owns it. It can read every Aisle Trace project owned by that organization, but no project outside it.

Copy the full key immediately. Aisle Trace shows it once, then keeps only a hash and short display prefix.

Open API keys
02

Connect the client

Send the key as a Bearer credential.

Set AISLE_TRACE_API_KEY in the environment that starts your agent. The hosted endpoint accepts Streamable HTTP requests and requires the key on every request.

Codex

Codex reads the Bearer token from the named environment variable instead of saving it in TOML. Its host-level MCP configuration is shared across Codex clients, so remove or disable this server before opening an untrusted workspace.

codex mcp add aisle-trace \
  --url https://mcp.aisletrace.com/mcp \
  --bearer-token-env-var AISLE_TRACE_API_KEY
Claude Code

Run this inside the trusted project that needs Aisle Trace. Claude Code's default local scope keeps the server out of unrelated projects. The single quotes preserve the environment-variable reference when it saves the header.

claude mcp add --transport http \
  --header 'Authorization: Bearer ${AISLE_TRACE_API_KEY}' \
  aisle-trace https://mcp.aisletrace.com/mcp
Cursor

Put this in the trusted project's .cursor/mcp.json. Cursor reads the key from the environment instead of saving it in JSON.

{
  "mcpServers": {
    "aisle-trace": {
      "url": "https://mcp.aisletrace.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AISLE_TRACE_API_KEY}"
      }
    }
  }
}
03

Use the data

List projects before asking a project question.

Restart or reload the client, confirm that Aisle Trace exposes four tools, then begin with this prompt:

List the Aisle Trace projects I can access.

Ask for archived projects explicitly when you need finished research that is hidden from the default list.

Choose a returned project identifier, then try a grounded research question:

In project [project ID], find current green tea promotions in JPY. For the cheapest observation, show the capture, extraction, and evidence provenance.

Current surface

Four tools, all read-only.

list_projects
List active projects by default, or request the organization’s archived projects.
query_observations
Read a filtered page of retail observations within one Aisle Trace project.
search_project_data
Search structured observations and capture context within one Aisle Trace project.
read_observation_provenance
Read the capture, extraction, contract, and evidence behind one observation.
04

End access

Revoke keys that are no longer needed.

Return to API keys in Aisle Trace and select Revoke. The client loses access immediately. Unknown and revoked keys receive the same non-disclosing unauthorized response.

Manage API keys

Direct integration

Use the same key with the read API.

Clients that do not use MCP can call the versioned Aisle Trace HTTP API. Send the same organization key as Authorization: Bearer shc_your_generated_key. These are selected stable read and search routes. The same key also authorizes write-capable machine API routes that this guide does not list.

https://app.aisletrace.com/api/v1
  • GET /projects
  • GET /projects/:projectId/locations
  • GET /projects/:projectId/captures
  • GET /projects/:projectId/observations
  • GET /projects/:projectId/observations.csv
  • GET /projects/:projectId/observations/:observationId/provenance
  • POST /projects/:projectId/search

Start with the project list. Keep every answer tied to its source.

Open Aisle Trace