diff --git a/docs.json b/docs.json
index e6bf580..9d5290f 100644
--- a/docs.json
+++ b/docs.json
@@ -60,6 +60,7 @@
                                 "pages": [
                                     "features/agent-skills",
                                     "features/hooks",
+                                    "features/model-settings",
                                     "features/rule-files"
                                 ]
                             }
diff --git a/features/automations.mdx b/features/automations.mdx
index fa42b20..db5d128 100644
--- a/features/automations.mdx
+++ b/features/automations.mdx
@@ -64,6 +64,10 @@ React to events from your integrations in real-time.
 5. Instruct MCP servers or integrations
 6. Save and enable
 
+<Tip>
+  Use [Model Settings](/features/model-settings) to set your workspace default agent/model and control which models are available to your team.
+</Tip>
+
 ## Beyond code
 
 Automations aren't limited to engineering tasks. With [MCP servers](/integrations/mcp), agents can work across your entire stack.
diff --git a/features/model-settings.mdx b/features/model-settings.mdx
new file mode 100644
index 0000000..79dd8e1
--- /dev/null
+++ b/features/model-settings.mdx
@@ -0,0 +1,59 @@
+---
+title: "Model Settings"
+description: "Configure default agents, provider keys, custom MCP servers, and model availability."
+---
+
+Use **Settings > Models** in the [dashboard](https://app.tembo.io) to control how your workspace selects and runs models.
+
+## Default agent
+
+Set the default agent and model Tembo uses for new tasks and automations.
+
+- Pick the default from a single dropdown in **Settings > Models**
+- You can still override agent/model per task or automation
+
+## Provider API keys
+
+You can manage model provider credentials in one place:
+
+- Anthropic API key
+- OpenAI API key
+- Amp API key
+- Cursor API key
+- AWS Bedrock access key, secret key, and region
+
+Keys are saved at the workspace level and used when a selected model requires that provider.
+
+## Custom MCP servers (global JSON)
+
+`globalMcpServers` lets you define shared MCP servers available across tasks and automations.
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "ghp_xxx"
+      }
+    }
+  }
+}
+```
+
+<Note>
+  This JSON is workspace-wide. Invalid JSON is rejected when you save.
+</Note>
+
+## Available models
+
+The **Available Models** list lets you enable or disable specific models for your organization.
+
+- Models are enabled by default
+- Org admins can toggle models on/off
+- Non-admin members can view status but cannot change it
+
+<Warning>
+  You cannot disable the model currently used by your default agent. Change the default agent model first.
+</Warning>
diff --git a/integrations/mcp.mdx b/integrations/mcp.mdx
index fc836c5..6598449 100644
--- a/integrations/mcp.mdx
+++ b/integrations/mcp.mdx
@@ -32,3 +32,34 @@ GitHub, Linear, Sentry, and Postgres MCP servers are automatically available whe
 ## Custom servers
 
 Bring your own MCP servers from the [Integrations page](https://app.tembo.io/integrations) using **Custom MCP**. Supports stdio, HTTP, and SSE, including OAuth.
+
+### Connection types
+
+#### Remote (HTTP/SSE)
+
+Use this for hosted MCP servers.
+
+- Required: `name`, `serverUrl`
+- Optional: static `headers` (for example, `Authorization`)
+- If the server requires OAuth, Tembo returns an authorization URL and completes setup after you authorize
+
+#### Stdio
+
+Use this for command-based MCP servers started in the sandbox.
+
+- Required: `name`, `command`
+- Optional: `args` (space-separated in UI), `env` variables
+
+Example:
+
+```json
+{
+  "type": "stdio",
+  "name": "github-mcp",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_TOKEN": "ghp_xxx"
+  }
+}
+```