Handling API Keys & Tokens Safely · GitHub Copilot Best Practices

Key insight: As you connect more MCPs, credential management becomes the #1 operational risk. A token accidentally committed to a repo or left in a config file is a real security incident. Getting this right once — early — saves significant pain later.

Not sure what to do? Ask OpenCode directly — "How should I store credentials for [tool name] MCP safely?" — and it will walk you through the right approach for your setup.

The core rule

When MCPs connect to tools like Webex, Jira or Airtable, they need a token — a kind of password that proves you have permission to access that tool. The golden rule is simple: the actual token should never be typed or pasted directly into any config file or chat window. Instead, you give the config file a label (like WEBEX_TOKEN), and the real value is stored separately in your system. OpenCode knows to look it up when it needs it. That way, if the config file is ever shared accidentally, there's nothing sensitive in it.

If you're not sure how to set this up, ask OpenCode — "How do I add my [tool name] token to my config without pasting the token directly in?" It can walk you through updating the files safely, without you ever needing to share the token with it.

Two types of config file — and why it matters

OpenCode has two places where settings can live. Understanding the difference is important for keeping credentials safe:

Global config

~/.config/opencode/opencode.json

Applies to every OpenCode session on your machine
Sits in your personal home folder — outside any project
Never automatically synced to GitHub or shared with anyone
The right place for MCP setup — it holds the labels that reference your credentials, never the credentials themselves

This is where MCP config lives. Safe as long as real tokens aren't pasted in directly.

Project-level config

./opencode.json (inside a project folder)

Applies only to that one project
Lives inside a folder you might push to GitHub
Useful for project-specific things — custom agents, instructions, prompts
Anything sensitive here is one accidental upload away from being public

Never put credentials here. Prompts and instructions only.

What never goes in a repo

If you use GitHub to store your projects, these things should never be uploaded or shared:

API keys, tokens, passwords — any kind of secret If it grants access to something, it doesn't belong on GitHub or in any shared location. Ever. Treat it the same as a password — you wouldn't put your email password in a shared folder.
Config files that contain real credentials Your global opencode.json is safe because it lives outside any project folder — but if you ever copy it somewhere inside a project, be careful. And never paste a real token into a project-level config.
Chat transcripts that contain tokens If you ever paste a token into an OpenCode chat (even by accident), treat it as compromised — meaning you should go back to the tool that issued it (Webex, Jira, Airtable, etc.), delete that token, and generate a fresh one. Chat logs are stored locally, but it's still bad practice.