Document .env discovery improvements (#626)

* Document improved env file discovery

* Regenerate clean markdown files

* Regenerate clean markdown files

* Regenerate clean markdown files

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: EricGustin

app/en/get-started/quickstarts/mcp-server-quickstart/page.mdx

@@ -80,17 +80,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 - **server.py** Entrypoint file with MCPApp and example tools
 - **pyproject.toml** Dependencies and project configuration
-- **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`
+- **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory.
 
 `server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample tools:
 
@@ -106,17 +106,17 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra
 
 <Tabs items={[".env file", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret:
+You can create a `.env` file at your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated project includes a `.env.example` file with the secret key name and example value.
+The generated project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 </Tabs.Tab>

app/en/guides/create-tools/tool-basics/build-mcp-server/page.mdx

@@ -76,17 +76,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 1. **server.py** Main server file with MCPApp and example tools. It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly.
 1. **pyproject.toml** Dependencies and project configuration
-1. **.env.example** Example `.env` file containing a secret required by one of the generated tools in `server.py`. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
+1. **.env.example** Example `.env` file at the project root containing a secret required by one of the generated tools in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
 
 ```python filename="server.py" showLineNumbers
 #!/usr/bin/env python3
@@ -171,17 +171,19 @@ Secrets are sensitive strings like passwords, API keys, or other tokens that gra
 
 <Tabs items={[".env file", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file at the same directory as your entrypoint file (`server.py`) and add your secret:
+You can create a `.env` file at your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated project includes a `.env.example` file with the secret key name and example value.
+Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the project root (`my_server/`), and it will be found even when running your server from a subdirectory like `src/my_server/`.
+
+The generated project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 </Tabs.Tab>

app/en/guides/create-tools/tool-basics/create-tool-secrets/page.mdx

@@ -68,13 +68,13 @@ Depending on where you're running your server, you can store your secret in a fe
 
 <Tabs items={[".env file", "Arcade Dashboard", "Arcade CLI", "Environment Variable"]}>
 <Tabs.Tab>
-You can create a `.env` file in the same directory as your entrypoint file (typically `server.py` by default) and add your secret:
+You can create a `.env` file in your project root directory and add your secret:
 
 ```env filename=".env"
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The project includes a `.env.example` file with the secret key name and example value.
+The project includes a `.env.example` file at the project root with the secret key name and example value.
 You can rename it to `.env` to start using it.
 
 ```bash
@@ -206,7 +206,7 @@ When your tool is executed, it will return: `"Got SECRET_KEY of length..."`. In
 ## Key Concepts
 
 - **Secure Access:** Secrets are accessed through context, not imported directly
-- **Environment Integration:** Works with both environment variables and .env files
+- **Environment Integration:** Works with both environment variables and `.env` files
 - **Error Handling:** Always handle the case where a secret might be missing
 - **Masking:** Never expose full secret values in logs or return values
 - **Declaration:** Use `requires_secrets` to make dependencies explicit
@@ -221,7 +221,7 @@ SECRET_KEY="supersecret"
 
 <Callout type="warning">
 
-For the code to work, you must define your environment variables locally or in a `.env` file.
+For the code to work, you must define your environment variables locally or in a `.env` file. Arcade will automatically search upward from the current directory to find your `.env` file.
 
 </Callout>
 

app/en/guides/deployment-hosting/arcade-deploy/page.mdx

@@ -105,7 +105,7 @@ Validating user is logged in...
 Validating pyproject.toml exists in current directory...
 ✓ pyproject.toml found at /path/to/your/project/pyproject.toml
 
-Loading .env file from current directory if it exists...
+Searching for .env file...
 ✓ Loaded environment from /path/to/your/project/.env
 
 Validating server is healthy and extracting metadata before deploying...

public/_markdown/en/get-started/quickstarts/mcp-server-quickstart.md

@@ -57,17 +57,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 -   **server.py**  with MCPApp and example
 -   **pyproject.toml** Dependencies and  configuration
--   **.env.example** Example `.env` file containing a secret required by one of the generated  in `server.py`
+-   **.env.example** Example `.env` file at the  root containing a secret required by one of the generated  in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory.
 
 `server.py` includes proper structure with command-line argument handling. It creates an `MCPApp` with three sample :
 
@@ -83,17 +83,17 @@ Secrets are sensitive strings like passwords, , or other tokens that grant acces
 
 ### .env file
 
-You can create a `.env` file at the same directory as your  (`server.py`) and add your secret:
+You can create a `.env` file at your  root directory and add your secret:
 
 ```bash
 # .env
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated  includes a `.env.example` file with the secret key name and example value. You can rename it to `.env` to start using it.
+The generated  includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 ### Environment Variable
@@ -216,7 +216,7 @@ Ensure you have set the environment variable in your terminal or `.env` file, an
 -   **Learn how to deploy your  server**: [Deploy your MCP server](/guides/deployment-hosting/arcade-deploy.md)
 
 
-Last updated on January 30, 2026
+Last updated on January 5, 2026
 
 [Call tools in IDE/MCP clients](/en/get-started/quickstarts/call-tool-client.md)
 [Overview](/en/get-started/agent-frameworks.md)

public/_markdown/en/guides/create-tools/tool-basics/build-mcp-server.md

@@ -56,17 +56,17 @@ This generates a Python module with the following structure:
 
 ```bash
 my_server/
+├── .env.example
 ├── src/
 │   └── my_server/
 │       ├── __init__.py
-│       ├── .env.example
 │       └── server.py
 └── pyproject.toml
 ```
 
 1.  **server.py** Main server file with MCPApp and example . It creates an `MCPApp`, defines tools with `@app.tool`, and will start the server with `app.run()` when the file is executed directly.
 2.  **pyproject.toml** Dependencies and  configuration
-3.  **.env.example** Example `.env` file containing a secret required by one of the generated  in `server.py`. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
+3.  **.env.example** Example `.env` file at the  root containing a secret required by one of the generated  in `server.py`. Arcade automatically discovers `.env` files by traversing upward from the current directory, so placing it at the project root makes it accessible from any subdirectory. Environments are loaded on server start, so **if you update the `.env` file, you will need to restart your server.**
 
 ```python
 # server.py
@@ -152,17 +152,19 @@ Secrets are sensitive strings like passwords, , or other tokens that grant acces
 
 ### .env file
 
-You can create a `.env` file at the same directory as your  (`server.py`) and add your secret:
+You can create a `.env` file at your  root directory and add your secret:
 
 ```bash
 # .env
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The generated  includes a `.env.example` file with the secret key name and example value. You can rename it to `.env` to start using it.
+Arcade automatically discovers `.env` files by traversing upward from the current directory through parent directories. This means you can place your `.env` file at the  root (`my_server/`), and it will be found even when running your server from a subdirectory like `src/my_server/`.
+
+The generated  includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it.
 
 ```bash
-mv .env.example .env
+mv ../../.env.example ../../.env
 ```
 
 ### Environment Variable
@@ -272,7 +274,7 @@ That’s it! Your  server is running and connected to your AI assistant.
 -   **Deploy your  server**: [Learn how to deploy your MCP server](/guides/deployment-hosting/arcade-deploy.md)
 
 
-Last updated on January 30, 2026
+Last updated on January 5, 2026
 
 [Compare MCP server types](/en/guides/create-tools/tool-basics/compare-server-types.md)
 [Create a tool with auth](/en/guides/create-tools/tool-basics/create-tool-auth.md)

public/_markdown/en/guides/create-tools/tool-basics/create-tool-secrets.md

@@ -62,14 +62,14 @@ Depending on where you’re running your server, you can store your secret in a
 
 ### .env file
 
-You can create a `.env` file in the same directory as your  (typically `server.py` by default) and add your secret:
+You can create a `.env` file in your  root directory and add your secret:
 
 ```bash
 # .env
 MY_SECRET_KEY="my-secret-value"
 ```
 
-The  includes a `.env.example` file with the secret key name and example value. You can rename it to `.env` to start using it.
+The  includes a `.env.example` file at the project root with the secret key name and example value. You can rename it to `.env` to start using it.
 
 ```bash
 mv .env.example .env
@@ -179,7 +179,7 @@ When your  is executed, it will return: `"Got SECRET_KEY of length..."`. In a re
 ## Key Concepts
 
 -   **Secure Access:** Secrets are accessed through , not imported directly
--   **Environment Integration:** Works with both environment variables and .env files
+-   **Environment Integration:** Works with both environment variables and `.env` files
 -   **Error Handling:** Always handle the case where a secret might be missing
 -   **Masking:** Never expose full secret values in logs or return values
 -   **Declaration:** Use `requires_secrets` to make dependencies explicit
@@ -193,7 +193,7 @@ When your  is executed, it will return: `"Got SECRET_KEY of length..."`. In a re
 SECRET_KEY="supersecret"
 ```
 
-For the code to work, you must define your environment variables locally or in a `.env` file.
+For the code to work, you must define your environment variables locally or in a `.env` file. Arcade will automatically search upward from the current directory to find your `.env` file.
 
 ```python
 # secrets.py
@@ -249,7 +249,7 @@ For HTTP transport, view your server’s API docs at [http://127.0.0.1:8000/docs
 
 For security reasons, Local HTTP servers do not currently support tool-level authorization and secrets. If you need to use tool-level authorization or secrets locally, you should use the stdio transport and configure the Arcade API key and secrets in your  connection settings. Otherwise, if you intend to expose your HTTP  to the public internet with \-level authorization and secrets, please follow the [deploying to the cloud with Arcade Deploy](/guides/deployment-hosting/arcade-deploy.md) guide or the [on-prem MCP server](/guides/deployment-hosting/on-prem.md) guide for secure remote deployment.
 
-Last updated on January 30, 2026
+Last updated on January 5, 2026
 
 [Create a tool with auth](/en/guides/create-tools/tool-basics/create-tool-auth.md)
 [Access runtime data](/en/guides/create-tools/tool-basics/runtime-data-access.md)

public/_markdown/en/guides/deployment-hosting/arcade-deploy.md

@@ -85,7 +85,7 @@ Validating user is logged in...
 Validating pyproject.toml exists in current directory...
 ✓ pyproject.toml found at /path/to/your/project/pyproject.toml
 
-Loading .env file from current directory if it exists...
+Searching for .env file...
 ✓ Loaded environment from /path/to/your/project/.env
 
 Validating server is healthy and extracting metadata before deploying...
@@ -143,7 +143,7 @@ You can use any of the available [Arcade clients](/references.md) to call the to
 
 Your  Server is now deployed and managed by Arcade, and ready to be used in your MCP clients!
 
-Last updated on January 30, 2026
+Last updated on January 5, 2026
 
 [Configure Arcade's engine](/en/guides/deployment-hosting/configure-engine.md)
 [Overview](/en/guides/security.md)