Skip to content

fix: mark SPACE_ID as optional and document multi-space usage #341

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Gonzalo Fleming (gonzafg2) wants to merge 4 commits into
base: main
Choose a base branch
from
Open

fix: mark SPACE_ID as optional and document multi-space usage #341

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fa498db
fix: mark SPACE_ID as optional and document multi-space usage
gonzafg2 Mar 17, 2026
5dfc0ca
fix: clarify that spaceId/environmentId apply to space-scoped tools only
gonzafg2 Mar 17, 2026
5c3b65c
fix: clarify that not all space-scoped tools accept environmentId
gonzafg2 Apr 2, 2026
3e37453
Merge branch 'main' into fix/space-id-optional-multi-space
gonzafg2 Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 24 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ This MCP server provides a comprehensive set of tools for content management, al

- Node.js
- npm
- A Contentful account with a [Space ID](https://www.contentful.com/help/spaces/find-space-id/)
- A Contentful account with one or more [Spaces](https://www.contentful.com/help/spaces/find-space-id/)
- [Contentful Management API personal access token](https://www.contentful.com/help/token-management/personal-access-tokens/)

### Installation
Expand Down Expand Up @@ -70,7 +70,7 @@ npm run build
| Environment Variable | Required | Default Value | Description |
| ------------------------------------ | -------- | -------------------- | ---------------------------------------------------- |
| `CONTENTFUL_MANAGEMENT_ACCESS_TOKEN` | ✅ Yes | - | Your Contentful Management API personal access token |
| `SPACE_ID` | ✅ Yes | - | Your Contentful Space ID |
| `SPACE_ID` | ❌ No | - | Default Contentful Space ID (can be overridden per tool call) |
| `ENVIRONMENT_ID` | ❌ No | `master` | Target environment within your space |
| `CONTENTFUL_HOST` | ❌ No | `api.contentful.com` | Contentful API host |
| `NODE_ENV` | ❌ No | `production` | Node Environment to run in |
Expand Down Expand Up @@ -98,6 +98,28 @@ Below is a sample configuration:
}
```

### Working with Multiple Spaces

The MCP server supports working with multiple Contentful spaces from a single instance. Most space-scoped tools (entries, assets, content types, etc.) accept `spaceId` and `environmentId` as parameters, allowing the AI assistant to target any space accessible by your token on each tool call. Some tools like `get_space` only require `spaceId`. Organization-level tools like `list_spaces` and `list_orgs` work across all accessible spaces without requiring these parameters.

To work with multiple spaces, omit `SPACE_ID` from your configuration and ensure your CMA token has access to all desired spaces:

```json
{
"mcpServers": {
"contentful-mcp": {
"command": "npx",
"args": ["-y", "@contentful/mcp-server"],
"env": {
"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "your-CMA-token"
}
}
}
}
```

The AI assistant can use `list_spaces` to discover available spaces and switch between them dynamically. If `SPACE_ID` is provided, it serves as the default but can be overridden on any tool call.

## 🛠️ Available Tools

| Category | Tool Name | Description |
Expand Down
26 changes: 24 additions & 2 deletions packages/mcp-server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ This MCP server provides a comprehensive set of tools for content management, al

- Node.js
- npm
- A Contentful account with a [Space ID](https://www.contentful.com/help/spaces/find-space-id/)
- A Contentful account with one or more [Spaces](https://www.contentful.com/help/spaces/find-space-id/)
- [Contentful Management API personal access token](https://www.contentful.com/help/token-management/personal-access-tokens/)

### Installation
Expand Down Expand Up @@ -66,7 +66,7 @@ npm run build
| Environment Variable | Required | Default Value | Description |
| ------------------------------------ | -------- | -------------------- | ---------------------------------------------------- |
| `CONTENTFUL_MANAGEMENT_ACCESS_TOKEN` | ✅ Yes | - | Your Contentful Management API personal access token |
| `SPACE_ID` | ✅ Yes | - | Your Contentful Space ID |
| `SPACE_ID` | ❌ No | - | Default Contentful Space ID (can be overridden per tool call) |
| `ENVIRONMENT_ID` | ❌ No | `master` | Target environment within your space |
| `CONTENTFUL_HOST` | ❌ No | `api.contentful.com` | Contentful API host |
| `NODE_ENV` | ❌ No | `production` | Node Environment to run in |
Expand Down Expand Up @@ -94,6 +94,28 @@ Below is a sample configuration:
}
```

### Working with Multiple Spaces

The MCP server supports working with multiple Contentful spaces from a single instance. Most space-scoped tools (entries, assets, content types, etc.) accept `spaceId` and `environmentId` as parameters, allowing the AI assistant to target any space accessible by your token on each tool call. Some tools like `get_space` only require `spaceId`. Organization-level tools like `list_spaces` and `list_orgs` work across all accessible spaces without requiring these parameters.

To work with multiple spaces, omit `SPACE_ID` from your configuration and ensure your CMA token has access to all desired spaces:

```json
{
"mcpServers": {
"contentful-mcp": {
"command": "npx",
"args": ["-y", "@contentful/mcp-server"],
"env": {
"CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "your-CMA-token"
}
}
}
}
```

The AI assistant can use `list_spaces` to discover available spaces and switch between them dynamically. If `SPACE_ID` is provided, it serves as the default but can be overridden on any tool call.

## 🛠️ Available Tools

| Category | Tool Name | Description |
Expand Down
4 changes: 2 additions & 2 deletions packages/mcp-server/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,8 +308,8 @@
"SPACE_ID": {
"type": "string",
"title": "SPACE_ID",
"description": "Contentful Space ID",
"required": true
"description": "Default Contentful Space ID (optional — omit to work with multiple spaces)",
"required": false
},
"ENVIRONMENT_ID": {
"type": "string",
Expand Down