Organization MCP Servers
Understand when to use environment MCP servers, when to use organization MCP servers, and how transports and OAuth identity scopes work in CloudCLI.
MCP servers give your agents extra tools: browser automation, GitHub context, database access, documentation search, internal APIs, and more. CloudCLI supports two different places to configure them: environment MCP servers and organization MCP servers.
Environment MCP servers
Environment MCP servers belong to one CloudCLI environment. Use them when the server is project-specific, experimental, or tied to a secret that should stay inside a single environment.
Environment MCP servers are a good fit for:
- A database MCP server pointed at one development database.
- A filesystem MCP server limited to one project folder.
- A one-off local server you are testing before sharing it with the team.
- Credentials that should not be reused across every environment.
Changes apply only to that environment. Existing agent sessions may need to restart before they see a newly added server.
Organization MCP servers
Organization MCP servers are managed from Settings > Configuration > Organization MCP. Admins add the server once, and CloudCLI propagates it to every environment in the organization across supported agent providers.
Organization MCP servers are a good fit for:
- Company-wide documentation or search tools.
- Shared SaaS integrations such as GitHub, Stripe, Supabase, or Context7.
- Standard browser automation tooling such as Playwright.
- Internal MCP servers that every environment should receive automatically.
When a new environment is created, CloudCLI applies the current organization MCP server list to that environment. Use Sync now on a server when you want to repair drift after an environment restart, provider config change, or temporary sync failure.
Choose a transport
| Transport | Use it for | What CloudCLI asks for |
|---|---|---|
stdio | A command that runs inside the environment, such as npx @playwright/mcp@latest or a Dockerized local server. | Command, arguments, and environment variables. |
http | A remote MCP endpoint hosted by a vendor or your own team. | URL, optional headers, and optionally OAuth. |
CloudCLI organization MCP supports stdio and modern HTTP MCP servers. For HTTP servers, use the server's MCP endpoint, often a URL ending in /mcp.
Choose an HTTP auth mode
For HTTP servers, CloudCLI supports two authentication patterns.
Static headers are best when the server expects an API key or bearer token. Add the required header in the modal, for example Authorization: Bearer <token> or CONTEXT7_API_KEY: <key>.
OAuth is best when the MCP provider supports browser-based authorization. After the server is created, users click Connect from the Organization MCP list. CloudCLI handles discovery, client registration when available, token storage, refresh, and propagation to environments.
Choose an OAuth identity scope
| Scope | What it means | Use it when |
|---|---|---|
| Shared | One organization-level connection is used for the server. | The server should act as a shared service account or admin-owned integration. |
| Per-member | Each member connects their own account. | Access should follow each person's permissions in the provider. |
For providers such as GitHub, Supabase, and Stripe, per-member OAuth is often safer because the agent only receives the access that the signed-in person granted. Use a shared connection only when your team intentionally wants one shared identity.
Recommended setup flow
- Decide whether the server belongs to one environment or the whole organization.
- Pick
stdiofor local commands orhttpfor hosted MCP endpoints. - For HTTP servers, choose static headers or OAuth based on the provider's documentation.
- Add the server in CloudCLI.
- For OAuth servers, click Connect and complete the provider sign-in.
- Open a fresh agent session and ask the agent to list or use the new MCP tools.