Skip to main content
The soma.yaml file was initially designed around a desired DX:
  1. Developers configure MCP integrations at development time
  2. These integrations often require secrets such as refresh tokens, access tokens, API Keys, client secrets, etc.
  3. Developers want to test these configurations locally first, many of them require an initial handshake process (e.g. OAuth2 Authorization Code Flow)
  4. Once configured locally, we store the encrypted values in the soma.yaml file
  5. When you deploy your agent to an environment, you configure encryption key access in the environment and on start, these secrets are syned into the environment database and cached in memory (all encrypted).
  6. Now your agent “Just Works” (TM) in production.
This was namely a design choice to allow developers to configure Oauth MCP function credentials and enable testing them at development time. These credentials are then encrypted and stored locally and can be safely committed to version control.