Jeffrey Harris

Getting DESIGN.md Design Systems Working with OpenCode's MCP

I've been running more powerful AI models lately and wanted to use opencode.ai to add some real styling to my blog. The stock template was fine to get started, but I didn't want it looking like every other default setup out there.

That led me to DESIGN.md, a site where people publish design systems as markdown files. Think of it like a design system registry. You browse, you download, you implement. Simple enough.

They have an MCP server, which means you can plug it directly into AI coding tools like OpenCode and query design systems right from your editor. In theory.

The Setup

OpenCode uses an opencode.jsonc config file where you declare your MCP servers. The DESIGN.md docs show you the standard MCP config:

{
  "mcpServers": {
    "designmd": {
      "command": "npx",
      "args": [
        "designmd-mcp"
      ],
      "env": {
        "DESIGNMD_API_KEY": "your-key-here"
      }
    }
  }
}

OpenCode's config format is a little different, it uses "mcp" at the top level and drops the mcpServers wrapper. So you end up with something like this:

{
  "mcp": {
    "designmd": {
      "type": "local",
      "command": ["npx", "designmd-mcp"],
      "enabled": true,
      "env": {
        "DESIGNMD_API_KEY": "dk_your_key_here"
      }
    }
  }
}

Straightforward. I plugged in my API key, fired up OpenCode, and asked it to grab a design system.

The Error

It failed with:

DESIGNMD_API_KEY environment variable is not set.

Wait, what? The key is right there in the config. I triple-checked the spelling, the quotes, the comma placement. All good. I even asked an OpenCode model to check my work.

Here's the thing (according to DeepSeek V4): the MCP tools that DESIGN.md exposes check process.env.DESIGNMD_API_KEY at runtime. When OpenCode starts the MCP server, it passes the env vars from the config stanza just fine, the server itself can see them. But the tool functions that the server exposes to the AI apparently run in a different context where that env var isn't inherited.

At least, that's its best guess after poking at it for a while.

The Fix

What worked was setting the environment variable at the shell level:

export DESIGNMD_API_KEY="dk_your_key_here"

Drop that in your .zshrc or .bashrc, open a new terminal, launch OpenCode, and suddenly everything works. The MCP tools can see the key because it's in the parent process environment that OpenCode inherits.

The Takeaway

None of this is documented anywhere obvious. The DESIGN.md MCP docs show you the MCP config format but don't mention that you might also need the shell env var. And the error message points you back to the MCP config, which is already correct.

If you're using DESIGN.md with OpenCode (or probably any MCP client that doesn't perfectly bridge server env vars to tool execution contexts), save yourself the head-scratching and add the key to your shell profile too. The double config is harmless, the MCP stanza still matters for the server itself, and it saves you from the confusing error loop.

A small doc update or a better error message would go a long way here. Until then, hopefully this saves someone the twenty minutes I spent going in circles.

But on the other hand, I have a better design for this little piece of my digital home.