AI / MCP Integration

Connect AI assistants to your data with secure token-based access and a review queue for all proposed changes.

What is MCP?

MCP stands for Model Context Protocol — a standard way to connect AI assistants (like Claude) directly to the Structa app. This allows AI tools to read and propose changes to your metaobject data safely and securely.

When you enable MCP, you give an AI assistant the ability to:

• Read information about your metaobject entries
• Suggest edits and updates to your data
• Propose bulk changes across multiple entries

Connecting to Structa's MCP Server

Structa exposes a remote MCP server that AI clients can connect to directly. The server URL is:

https://metaobject-editor.heystructa.com/api/mcp

Connect with Claude (claude.ai)

1. Open claude.ai and go to Settings (click your profile icon).
2. Click Connectors in the sidebar.
3. Scroll down and click Add custom connector.
4. Enter the Structa MCP server URL: https://metaobject-editor.heystructa.com/api/mcp
5. Click Add and complete the authentication flow.
6. Once connected, Structa's tools and resources will be available in your Claude conversations.

Connect with Claude Desktop

For the full official guide, see Connecting to local MCP servers.

1. Open Claude Desktop and go to Settings from the Claude menu in your system's menu bar.
2. Navigate to the Developer tab in the left sidebar and click Edit Config. This opens your config file located at:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Add the following to the mcpServers object (replace YOUR_TOKEN with your API token from the Structa app):

   {
     "mcpServers": {
       "structa": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://metaobject-editor.heystructa.com/api/mcp",
           "--header",
           "Authorization:Bearer YOUR_TOKEN"
         ]
       }
     }
   }

4. Save the file, then completely quit and restart Claude Desktop.
5. Once restarted, you should see an MCP server indicator in the bottom-right corner of the conversation input. Click it to verify that Structa's tools are available.

Connect with Other MCP Clients

Any MCP-compatible client can connect to Structa's remote server using the URL above. For a general guide on connecting to remote MCP servers, see the MCP documentation on connecting to remote servers.

What the AI Can Do

Once connected, the AI assistant can:

• List definitions — see all your metaobject types and their fields
• Read entries — access metaobject entry data
• Propose changes — suggest edits to field values across entries
• Create entries — propose new metaobject entries

All proposed changes land in the Review Queue — nothing is written to Shopify without your approval.

---

Managing API Tokens

Where to Find MCP Settings

In the Structa app, navigate to MCP Integration in the main menu. This is where you manage all API tokens used by AI assistants.

What Are API Tokens?

An API token is a unique, secure password that allows an AI tool to access your metaobject data. Each token:

• Can be given a custom label (e.g., "Production Agent", "Claude Integration")
• Has an expiration date
• Can be revoked (disabled) at any time
• Is shown only once after creation — save it somewhere safe

Creating a New Token

1. Click the Generate Token button
2. Enter a Token Label — this helps you identify which AI tool is using this token
3. Select an Expiration Period:
   • 30 days — Short-term, more secure
   • 90 days — Standard duration
   • 365 days — Long-term access
4. Click Generate
5. A modal will appear showing your new token — copy it immediately to a safe location
6. Once you close the modal, the token is hidden and cannot be shown again

Understanding Token Status

Each token displays its status as a colored badge:

Status	Color	Meaning
Active	Green	The token is currently valid and can be used by an AI assistant.
Expired	Orange	The token's expiration date has passed. Any AI assistant using it will be denied access. You can still revoke it if needed.
Revoked	Red	You manually disabled this token. Access is denied immediately. Revoked tokens cannot be reactivated — generate a new one instead.

Viewing Token Details

For each token, you can see:

• Created date — When the token was first generated
• Expires date — When the token will automatically expire
• Last used date — The last time an AI assistant used this token to access your data
• Pending changes — How many changes proposed by this token are waiting in the Review Queue

Revoking a Token

To stop an AI assistant from accessing your data:

1. Find the token in the list
2. Click the Revoke button (only visible for active, non-expired tokens)
3. Confirm that you want to revoke the token
4. The token will be immediately disabled and any AI using it will lose access

This is useful if you want to stop using a particular AI integration, a token may have been compromised, or you are no longer working with a specific tool.

Token Security Best Practices

Review Queue

What is the Review Queue?

When an AI assistant proposes changes to your metaobject entries, those changes do not go directly to Shopify. Instead, they appear in the Review Queue, where you can see exactly what the AI wants to change and decide whether to approve or reject it. This gives you complete control — you review every change before it is saved.

Click Review Queue in the app's main navigation to access it. You will see all pending, approved, and rejected changes in one place.

The Three Tabs

The Review Queue has three tabs that show changes at different stages:

Tab	What it shows	What you can do
Pending (default)	Changes waiting for your decision	Click Approve or Reject on each change. This is where you do your review work.
Approved	Changes you have approved	Browse your approval history. These have been submitted to Shopify.
Rejected	Changes you have rejected	Browse your rejection history. These were not submitted to Shopify.

Reviewing a Single Change

Each change is displayed as a card showing:

1. Change Type Badge — indicates the operation:
   • Create (Green) — A new metaobject entry will be created
   • Update (Blue) — An existing entry will be modified
   • Delete (Red) — An entry will be deleted
2. Field Name — Which field is being changed. If multiple fields are being updated, it shows "Multiple fields".
3. AI Tool Name — The token label of the AI that proposed this change.
4. Timestamp — How long ago the change was proposed (e.g., "5m ago").
5. Current vs. Proposed Values — Click to expand and see the actual changes.

Viewing the Diff

To see what the AI wants to change:

1. Click anywhere on the change card to expand it
2. The Current (left side) shows the value that exists now
3. The Proposed (right side) shows what the AI wants it to be
4. Values are color-coded:
   • Red panels = values being removed
   • Green panels = values being added

For batch updates (when multiple fields are changed at once), each field shows its own side-by-side comparison.

Approving a Change

To accept a proposed change:

• Single Approval — Click the Approve button on that change
• Bulk Approval — Select multiple changes with checkboxes, then click Approve Selected or Approve All

Once approved, the change gets a green "Approved" badge, a green line appears on the left side of the card, and it is added to your approval list for submission.

Rejecting a Change

To decline a proposed change:

• Single Rejection — Click the Reject button on that change
• Bulk Rejection — Select multiple changes with checkboxes, then click Reject Selected or Reject All

Once rejected, the change gets a red "Rejected" badge, a red line appears on the left side of the card, and the AI's proposed change is discarded.

Bulk Actions

Use these when reviewing many changes at once:

• Select changes — Click the checkboxes next to individual changes, or click the main checkbox at the top to select/deselect all pending changes on the current page.
• Bulk Approve or Reject — After selecting changes, click Approve [X] Selected or Reject [X] Selected. Or click Approve All / Reject All to process all pending changes at once.
• Clear — Undo your selection if you have marked changes for approval/rejection but want to start over. This clears your staging area without submitting anything.

Submitting Your Decisions

At the bottom of the page, a sticky action bar shows how many changes are marked for approval and rejection, along with buttons to submit or clear your decisions.

Once you have marked all the changes you want to approve or reject:

1. Click the Submit button at the bottom
2. The app will send all your decisions to Shopify
3. You will see a confirmation: "X approved, Y rejected"
4. Approved changes are now live in Shopify
5. Rejected changes are discarded

Pagination

If you have many pending changes, use the page indicator at the top to navigate. Each page shows up to 20 changes. Your approvals and rejections are staged across all pages — you can flip between pages without losing your progress.

Common Workflows

Approving All Changes from a Trusted AI Tool

1. Go to the Pending tab
2. Click the checkbox at the top to select all pending changes
3. Click Approve All Selected
4. Review the sticky bar at the bottom to confirm the count
5. Click Submit

Reviewing Changes One by One

1. Go to the Pending tab
2. For each change, click to expand and see the diff
3. Click Approve or Reject below the change details
4. Move to the next change
5. When done, click Submit at the bottom

Backing Out of a Decision

If you have marked a change but want to reconsider, click Undo on that change. The card will return to its unmarked state, and you can make your decision again when ready.

Checking the History of Approved Changes

1. Click the Approved tab
2. Browse through the changes you have accepted
3. See which AI tool proposed each change and when
4. Use pagination to look back through older approvals

Tips for Safe AI Integration

• Review before approving — Always check the diff to understand what is being changed.
• Start with short-lived tokens — Use 30-day tokens while testing an AI integration.
• Monitor token usage — Check the "Last used" date to ensure the token is being used as expected.
• Use clear labels — If you have multiple AI tools, give each token a distinct label.
• Keep the Review Queue clean — Regularly process pending changes so they do not pile up.
• Check AI quality — Over time, you will learn if an AI tool makes good suggestions or needs adjustment.

Troubleshooting

A token has expired — what now?

1. Go to MCP Integration
2. Generate a new token with your preferred expiration length
3. Give the new token to your AI tool
4. The expired token is automatically revoked and will not accept new requests

I rejected changes, but I want to undo that

Once you submit your decisions, they cannot be undone. Check the Rejected tab to see what was rejected, and you can ask the AI to propose those changes again.

A pending change has been sitting for a long time

1. Go to the Review Queue
2. Check the timestamp on the change
3. If the AI is not proposing new changes, its token may have expired or been revoked
4. Generate a new token if needed and share it with the AI tool

I do not see any pending changes

This is normal. It means the AI has not proposed any changes yet, or you have already approved/rejected all pending changes. Check the Approved and Rejected tabs to see the history of processed changes.

How It All Works Together

Throughout this process, you maintain complete control — no changes are applied without your explicit approval.