> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trysoma.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Appendix: The Role of soma.yaml

> How the soma.yaml file works

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.