Workspaces

Workspaces provide isolated environments for your projects and tools within an organization. Understanding how workspaces work is crucial for organizing your resources effectively and managing access control.

What are Workspaces?

A workspace is an isolated environment within an organization where you group related projects and tools. Think of a workspace as a separate "room" within your organization - everything inside a workspace is isolated from other workspaces, but they all share the same organization-level settings like billing and team management.

Each workspace is a self-contained environment that contains:

• MCP servers and tools - All the MCP servers you create and the tools within them exist within a specific workspace. This is where you actually build and organize your tools.

• API keys for authentication - API keys are created at the workspace level and can be used to authenticate requests to MCP servers within that workspace. Each workspace has its own set of API keys.

• Encrypted secrets for configuration - Secrets are stored at the workspace level and can be accessed by all tools within that workspace. This is where you store sensitive information like API keys for external services, database passwords, and other configuration values.

• Workspace-specific members - While team members belong to the organization, you can control which workspaces each member has access to. This allows fine-grained access control - someone might have access to a "Development" workspace but not the "Production" workspace.

Why Use Multiple Workspaces?

Workspaces provide several important benefits:

• Environment separation - You can create separate workspaces for development, staging, and production. This ensures that development work doesn't accidentally affect production tools.

• Project organization - Different projects can have their own workspaces, making it easy to find and manage related tools.

• Team separation - Different teams can work in different workspaces, with access control ensuring teams only see what they need to see.

• Client separation - If you're building tools for multiple clients, each client can have their own workspace with complete isolation.

• Security isolation - Secrets and API keys in one workspace are completely inaccessible to tools in other workspaces, providing strong security boundaries.

When to Create a New Workspace

You should create a new workspace when:

• You need to separate development and production environments

• You're starting a new project that should be kept separate from existing projects

• You need different access controls for different groups of tools

• You're building tools for a different client or business unit

• You want to test new tools without affecting existing ones

For simple use cases, you might only need one workspace. As your needs grow, you'll likely want to create additional workspaces for better organization and security.

Creating Workspaces

Creating a workspace is straightforward and is one of the first things you'll do after creating an organization. Here's a detailed guide:

The Creation Process

• Navigate to your organization - From the organization dashboard, you'll see a list of workspaces (which will be empty if this is your first workspace). The dashboard shows all workspaces in your organization and provides quick access to create new ones.

• Click "Create Workspace" - This button is typically at the top of the workspaces list or in a prominent location on the dashboard. Clicking it opens a form to create a new workspace.

• Enter workspace details - You'll need to provide:

• **Name** - Give your workspace a descriptive name that clearly indicates its purpose. Examples: "Customer Support Tools", "Sales Automation", "Development Environment", or "Production". Choose a name that will still make sense months from now when you have many workspaces. - **Description** - Optionally describe what this workspace is for. This helps you and your team remember its purpose later. For example: "Tools for the customer support team to manage tickets and customer data" or "Development workspace for testing new tools before production deployment".

- **Configure workspace settings (optional)** - For your first workspace, you can use the default settings. As you get more advanced, you might configure:

• Default execution timeouts - Rate limiting settings - Resource limits - Workspace-specific notifications These can usually be changed later, so don't worry about getting them perfect initially.

- **Save the workspace** - Once you've entered the details, click "Create" or "Save" to create the workspace. ### What Happens After Creation

Once your workspace is created, you'll be taken to the workspace view. This is where you can:

• See all MCP servers in this workspace

• Create new MCP servers

• Manage API keys

• Manage secrets

• Configure workspace settings

• Manage workspace members

Your workspace starts empty - you'll need to create MCP servers and tools within it. But the workspace is ready to use immediately.

Understanding API Keys

API keys are used to authenticate requests to your MCP servers. They're a critical security feature that ensures only authorized clients (like AI assistants) can connect to and use your tools.

What API Keys Do

When an AI assistant wants to connect to your MCP server, it needs to provide an API key. The platform checks this key to verify that the request is authorized. Without a valid API key, the request is rejected.

API keys serve several important purposes:

• Authentication - They prove that the client is authorized to access your MCP servers

• Access control - You can create different API keys for different purposes and revoke them individually if needed

• Usage tracking - You can see which API key was used for each request, helping you understand usage patterns

• Security - If an API key is compromised, you can revoke it without affecting other keys

API Key Characteristics

• Workspace-scoped - Each API key belongs to a specific workspace. An API key from one workspace cannot be used to access MCP servers in another workspace. This provides isolation and security.

• Multiple keys supported - You can create multiple API keys for the same workspace. This is useful for:

• Different environments (one key for development, one for production) - Different clients or applications - Different team members or services - Key rotation (creating a new key before revoking an old one)

- **Shown only once** - When you create an API key, it's displayed once and then never shown again. This is a security feature - if someone gains access to your account, they can't see existing API keys. Make sure to copy and store your API keys securely when you create them. - **Revocable** - You can revoke (delete) API keys at any time. When you revoke a key, any clients using it will immediately lose access. This is useful if you suspect a key has been compromised or if you no longer need it. ### Best Practices for API Keys

• Rotate keys regularly - Periodically create new keys and revoke old ones. This limits the damage if a key is compromised.

• Use descriptive names - When creating keys, give them descriptive names like "Production - ChatGPT" or "Development - Claude". This helps you remember what each key is for.

• Store keys securely - Never commit API keys to code repositories or share them in insecure channels. Use secure password managers or secret management systems.

• Revoke unused keys - If you're no longer using an API key, revoke it. This reduces your attack surface.

• Monitor key usage - Regularly check which keys are being used and revoke any that show suspicious activity.

Secrets Management

Secrets are encrypted configuration values that you can store in a workspace and access from your tools. They're essential for securely storing sensitive information like API keys for external services, database passwords, authentication tokens, and other configuration values.

Why Use Secrets?

When building tools, you often need to connect to external services or databases. These connections typically require credentials like API keys or passwords. You have two options:

• Hardcode credentials in your tool code - This is a security risk. If someone gains access to your code, they have your credentials. Also, if you need to change a credential, you have to update every tool that uses it.

• Use secrets - Store credentials as encrypted secrets in the workspace. Tools can access them securely, and you can update them in one place without touching your tool code.

Secrets are the secure, recommended approach.

How Secrets Work

• Encrypted at rest - Secrets are encrypted when stored in the database. Even if someone gains access to the database, they can't read your secrets without the encryption keys.

• Accessible via the config parameter - When a tool executes, it receives a config parameter that contains all the secrets from the workspace. You can access secrets like config.API_KEY or config.DATABASE_PASSWORD in your tool code.

• Workspace-scoped - Secrets stored in one workspace are only accessible to tools in that workspace. Tools in other workspaces cannot access them. This provides isolation and security.

• Never exposed in code - Secrets are never shown in tool code, logs, or error messages. They're only accessible through the config parameter during tool execution.

What to Store as Secrets

Use secrets for any sensitive information that your tools need:

• API keys - Keys for external services like Stripe, SendGrid, or other APIs

• Authentication tokens - OAuth tokens, JWT tokens, or other authentication credentials

• Database credentials - Database connection strings, usernames, and passwords

• Service credentials - Credentials for cloud services, third-party integrations, or internal systems

• Configuration values - Any sensitive configuration that shouldn't be hardcoded

Best Practices for Secrets

• Never commit secrets to code - This is critical. Secrets should only exist in the workspace's secret store, never in your tool code.

• Use descriptive names - Name your secrets clearly, like STRIPE_API_KEY or DATABASE_PASSWORD. This makes it clear what each secret is for.

• Rotate secrets regularly - Periodically update secrets, especially if you suspect they may have been compromised.

• Use different secrets for different environments - If you have development and production workspaces, use different secrets for each. Never use production secrets in development.

• Document secret usage - Keep notes on which tools use which secrets so you know what will break if you update a secret.

Accessing Secrets in Tools

In your tool code, you access secrets through the config parameter:

async function execute(params, config) { // Access a secret const apiKey = config.STRIPE_API_KEY; // Use the secret in your code const response = await fetch('https://api.stripe.com/v1/...', { headers: { 'Authorization': `Bearer ${apiKey}` } }); return { success: true, data: response }; }

If a secret doesn't exist, config.SECRET_NAME will be undefined. Always check that secrets exist before using them.

Workspace Isolation and Security

One of the most important features of workspaces is complete isolation. This means that resources in one workspace cannot access or interfere with resources in another workspace.

What Isolation Means

Workspace isolation provides several critical security and organizational benefits:

• Resource isolation - MCP servers and tools in one workspace cannot access or see resources in another workspace. This means you can safely have development and production workspaces in the same organization without worrying about accidental cross-contamination.

• API key isolation - API keys from one workspace cannot be used to access MCP servers in another workspace. This ensures that if an API key is compromised, the damage is limited to that specific workspace.

• Secret isolation - Secrets stored in one workspace are completely inaccessible to tools in other workspaces. This means you can use different credentials for development and production without any risk of mixing them up.

• Member access control - You can grant team members access to specific workspaces. Someone might have access to a "Development" workspace but not the "Production" workspace, providing fine-grained access control.

Why Isolation Matters

Isolation is crucial for:

• Security - If one workspace is compromised, others remain secure

• Environment separation - Development work can't accidentally affect production

• Client separation - If you're building tools for multiple clients, each client's data and tools are completely isolated

• Testing - You can test new tools in a separate workspace without affecting existing tools

• Compliance - Isolation helps meet regulatory requirements for data separation

Workspace Members and Access Control

While team members belong to the organization, you can control which workspaces each member has access to. This provides fine-grained access control.

How Workspace Access Works

When you invite someone to your organization, they become an organization member with a role (Owner, Admin, or Member). However, you can also control their access to specific workspaces:

• Organization Owners and Admins - Typically have access to all workspaces by default

• Organization Members - Can be granted access to specific workspaces

• Workspace-specific permissions - You can grant someone access to a workspace even if they're a Member at the organization level

Managing Workspace Access

To manage who has access to a workspace:

• Navigate to the workspace

• Go to workspace settings

• Find the "Members" or "Access" section

• Add or remove members as needed

This allows you to create workspaces that only specific team members can access, providing additional security and organization.

Best Practices for Workspaces

• Use descriptive names - Choose workspace names that clearly indicate their purpose. You'll thank yourself later when you have many workspaces.

• Separate environments - Always use separate workspaces for development, staging, and production. Never mix them.

• Use different secrets per environment - Each workspace should have its own set of secrets. Never share secrets between development and production.

• Limit access appropriately - Only give team members access to workspaces they actually need. Use workspace access control as a security feature.

• Document workspace purposes - Use descriptions to document what each workspace is for. This helps team members understand the organization.

• Regular cleanup - Periodically review your workspaces and archive or delete ones you no longer need.

• Monitor usage - Keep an eye on which workspaces are being used and which are dormant. This helps you understand your organization's needs.