Adobe Commerce + OpenCode: Complete MCP Integration

Adobe Commerce is a MCP server that Adobe Commerce MCP server.

When integrated with OpenCode, you can:

• Analyze and explore Adobe Commerce GraphQL schema structure
• Write and test GraphQL queries and mutations for Adobe Commerce
• Interact with Adobe Commerce business logic through GraphQL

This guide provides step-by-step instructions to set up Adobe Commerce in OpenCode, including configuration, examples, and troubleshooting.

What You'll Achieve

After completing this setup:

• Adobe Commerce will be fully integrated and operational
• You can use Adobe Commerce tools directly in OpenCode
• All Adobe Commerce capabilities will be available for your workflows
• Access to 4 different tools

Prerequisites

Before starting, ensure you have:

• Node.js
• npm
• Adobe Commerce environment
• OpenCode installed and configured
• Compatible operating system (macOS, Linux, Windows)

Installation

Step 1: Install Adobe Commerce

Install using npm:

npx -y @rafaelcg/adobe-commerce-dev-mcp@latest

Verify installation:

npx @rafaelcg/adobe-commerce-dev-mcp@latest --help

Configuration

Step 2: Configure OpenCode

1. Locate your configuration file:

2. Add server configuration:

Configure MCP servers in your `opencode.json` or `opencode.jsonc`:

```json
{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "environment": {
        "API_KEY": "$API_KEY"
      },
      "timeout": 5000
    },
    "remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      }
    }
  }
}

Disable a server temporarily:

{
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["npx", "-y", "mcp-server"],
      "enabled": false
    }
  }
}

3. **Restart OpenCode**

Completely quit and restart OpenCode to load the new configuration.



## Examples

Once configured, you can use Adobe Commerce in OpenCode:

### Explore GraphQL Schema

Introspect Adobe Commerce admin GraphQL schema

**Ask OpenCode:** "Show me the available GraphQL schema for product management in Adobe Commerce"

**Expected Result:** Detailed schema information including product types, fields, and available operations

### Create Product Query

Build GraphQL query to retrieve product information

**Ask OpenCode:** "Help me write a GraphQL query to get product details including name, price, and inventory status"

**Expected Result:** Well-formed GraphQL query with proper field selection and structure

### Customer Management Operation

Develop customer-related GraphQL operations

**Ask OpenCode:** "Create a GraphQL mutation to update customer profile information"

**Expected Result:** GraphQL mutation with proper input types and customer field updates

### Order Processing Query

Build order management GraphQL operations

**Ask OpenCode:** "Write a GraphQL query to retrieve order history with product details and shipping information"

**Expected Result:** Complex GraphQL query with nested relationships and order data structure



## Testing Your Setup

1. Run opencode in terminal
2. Add "use the mcp_name tool" to your prompts
3. Verify tool execution and response



## Troubleshooting

### Common Issues

#### Schema Introspection Failed

**Symptoms:** Schema not accessible, GraphQL endpoint errors, Authentication failures

**Cause:** Invalid GraphQL endpoint URL or authentication token

**Solution:**
- Verify Adobe Commerce GraphQL endpoint is accessible
- Check admin integration token has proper permissions
- Test endpoint manually with GraphQL client
- Ensure Adobe Commerce instance is running and configured

#### NPM Package Installation Error

**Symptoms:** Package not found, Installation timeouts, Version conflicts

**Cause:** Network issues, package registry problems, or dependency conflicts

**Solution:**
- Clear npm cache: npm cache clean --force
- Try alternative registry: npm install --registry https://registry.npmjs.org/
- Check network connectivity and proxy settings
- Update npm to latest version: npm install -g npm@latest

#### GraphQL Operation Syntax Error

**Symptoms:** Syntax validation errors, Malformed query messages, Parser errors

**Cause:** Invalid GraphQL syntax or schema incompatibility

**Solution:**
- Validate GraphQL syntax with online validator
- Check field names match schema definitions
- Ensure proper query structure and formatting
- Use introspect_admin_schema to verify available fields

#### Windows Command Execution Error

**Symptoms:** Command not recognized, Execution policy errors, Path issues

**Cause:** Windows-specific command execution or security policy restrictions

**Solution:**
- Use cmd configuration: "command": "cmd", "args": ["/c", "npx", ...]
- Check PowerShell execution policy: Set-ExecutionPolicy RemoteSigned
- Verify Node.js and npm are in system PATH
- Run terminal as administrator if needed

#### MCP Server Not Loading

**Symptoms:** Server not appearing in tools, Timeout errors, Command not found

**Cause:** Invalid configuration, missing dependencies, or timeout too short

**Solution:**
- Verify command array is correct in opencode.json
- Check environment variables are set properly
- Increase timeout value if server takes longer to start
- Test MCP server command independently in terminal

#### Context Limit Exceeded

**Symptoms:** Context too large errors, Slow responses, Truncated output

**Cause:** Too many MCP servers adding to context

**Solution:**
- Disable unused MCP servers with enabled: false
- Use per-agent tool configuration to limit active MCPs
- Avoid MCP servers that add many tokens (e.g., GitHub MCP)

#### Remote Server Connection Failed

**Symptoms:** Cannot connect to remote MCP, Authentication errors

**Cause:** Invalid URL, missing headers, or network issues

**Solution:**
- Verify remote server URL is correct
- Check authorization headers are properly configured
- Ensure environment variables for tokens are set

#### Adobe Commerce not appearing in OpenCode

**Symptoms:** Server not listed, Tools not available

**Cause:** Configuration or installation issue

**Solution:**
- Verify configuration syntax
- Check Adobe Commerce installation
- Restart OpenCode
- Check logs for error messages



## Next Steps

Now that Adobe Commerce is integrated with OpenCode:

- Explore all Adobe Commerce capabilities through OpenCode
- Check out other MCP servers that work with OpenCode
- Join the MCP community for tips and support
- Consider contributing to Adobe Commerce development

## Need Help?

- Search for [Adobe Commerce documentation](https://www.mcpstack.org)
- Check the [OpenCode MCP guide](https://www.mcpstack.org/clients)
- Join the MCP community discussions