IBX-11536: MCP Servers#3106
Conversation
mcp_guide.md heading `# Model Context Protocol and [[= product_name_base =]] MCP Servers` was used as-is, without the variable replaced.
Apply SonarCloud Code Analysis warning's suggestion
# Conflicts: # docs/product_guides/product_guides.md # mkdocs.yml
|
code_samples/ change report
|
| <base href="../"> | ||
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> |
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> | ||
| <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script> |
| <base href="../"> | ||
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> |
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> | ||
| <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script> |
| <base href="../"> | ||
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> |
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> | ||
| <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script> |
| <base href="../"> | ||
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> |
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> | ||
| <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script> |
| <base href="../"> | ||
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> |
| <link rel="icon" href="images/favicon.png"/> | ||
| <link rel="stylesheet" href="css/base.css"> | ||
| <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css"> | ||
| <script src="https://cdn.jsdelivr.net/npm/fuse.js@3.4.6"></script> |
There was a problem hiding this comment.
Just a partial review for now, starting with https://ez-systems-developer-documentation--3106.com.readthedocs.build/en/3106/ai/mcp/mcp_config/#example I've just read quickly till the end to get the general idea.
The most important comment is this one:
https://github.com/ibexa/documentation-developer/pull/3106/changes#r3219594627
I like the content, though at the end I felt it was more of a draft, not always following how we write.
Two additional comments:
- let's choose AI agents or AI applications and use them consistency
- Let's use JWT authentication, not just "JWT"
| #!/bin/bash | ||
| set -e | ||
|
|
||
| baseUrl='http://localhost' # Adapt to your test case |
There was a problem hiding this comment.
Just reading the example for now, is this SiteAccess-aware? How do I pass it - in the URL or with some header, like in REST?
There was a problem hiding this comment.
It's SiteAccess aware through regular URL matching.
I have this sentence in "Configure MCP server":
It's accessible with the path
/mcp/example(for example, onhttp://localhost/mcp/exampleandhttp://localhost/admin/mcp/example).
There was a problem hiding this comment.
And since c7937ee I now have this in MCP server options path description:
MCP server endpoint path (appended to SiteAccess-aware base URL)
Co-authored-by: Marek Nocoń <mnocon@users.noreply.github.com> Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
barw4
left a comment
There was a problem hiding this comment.
Awesome work 👏🏻
One more global comment, should we also document Resources like we did with Prompts?
| - create MCP servers [by using YAML configuration](mcp_config.md#mcp-server-configuration) | ||
| - assign different [tools](mcp_config.md#built-in-tools), prompts, and resources to different MCP servers, varying them for each site | ||
| - [create custom server capabilities](mcp_usage.md#create-capability-class) with PHP API | ||
|
|
There was a problem hiding this comment.
I would add the information that 'you can utilize predefined Ibexa tools from src/lib/Tools directory by adding them to your server' - obviously with better wording.
There was a problem hiding this comment.
I can split to emphase on the built-in tools link.
See https://github.com/ibexa/documentation-developer/pull/3106/changes#r3234431059
| While [AI actions](ai_actions_guide.md) integrate AI to the back office, | ||
| [[= product_name =]]'s [MCP servers](https://modelcontextprotocol.io/docs/learn/server-concepts) offer an API usable by AI agents outside the system. | ||
|
|
||
| Some AI agents can use directly REST API or GraphQL API if their users explain to them how to do it in prompts, in skill files, etc. |
There was a problem hiding this comment.
Maybe it's worth mentioning the advantages of MCP vs REST - here is unified cheatsheet: https://glama.ai/blog/2025-06-06-mcp-vs-api
There was a problem hiding this comment.
Thanks for this resource. I should be able to strengthen the next sentence.
| In `config/packages/security.yaml`, | ||
|
|
||
| - uncomment the `ibexa_jwt_rest` firewall to allow the request of JWT tokens through REST or GraphQL | ||
| - uncomment the `ibexa_jwt_mcp` firewall to allow the use of JWT authentication against MCP servers |
There was a problem hiding this comment.
this part was removed from recipes therefore there will be no ibexa_jwt_mcp configuration to be uncommented - as it's opt in package I assume it has to be added manually, wdyt?
There was a problem hiding this comment.
Some LTS Update seem to have recipe entries. Maybe it can be done. It should be investigated.
There was a problem hiding this comment.
In theory, it should be doable with recipes - with the add-lines configurator.
Doc: symfony/flex#975
Example usage: https://github.com/symfony/recipes/blob/main/symfony/panther/1.0/manifest.json#L28
|
|
||
| - `Ibexa\Mcp\Tool\TranslationTools` | ||
| - `list_languages`: Lists all languages in the current SiteAccess | ||
| - `list_content_translations`: Lists languages in which given content item has translations |
There was a problem hiding this comment.
https://github.com/ibexa/mcp/pull/8 another tool by @bnowak in progress, something to keep an eye on
There was a problem hiding this comment.
| ### Discovery cache | ||
|
|
||
| Discovery is cached to avoid scanning for capabilities on every request. | ||
| A PSR-6 or PSR-16 cache pool must be provided for this caching. |
There was a problem hiding this comment.
worth mentioning that when using tagaware.filesystem cache in order to see changes we need to also clear var/share: https://symfony.com/blog/new-in-symfony-7-4-share-directory (something to verify)
There was a problem hiding this comment.
Good. I have it in https://ez-systems-developer-documentation--3106.com.readthedocs.build/en/3106/ai/mcp/mcp_usage/#create-capability-class but could be mentioned here…
| For prompt, the `servers` parameter is required. | ||
| So, the example prompt has to use it to be associated with the `example` server. | ||
|
|
||
| During development and testing, you may have to clear the cache to make sure new or modified capabilities are properly re-discovered. |
| [[= include_code('code_samples/mcp/stdio.mcp.json') =]] | ||
| ``` | ||
|
|
||
| The `mcp-ibexa-example-wrapper.sh` is a script asking for a JWT token then establishing a connection with the MCP server. |
There was a problem hiding this comment.
Hmm, I have some concerns with providing example testing scripts that touch security. Since MCP ideally should be utilized with OAuth flow and we are not yet there, maybe for our own safety we could skip this part?
Co-authored-by: Bartek Wajda <bartlomiej.wajda@ibexa.co> Co-authored-by: Adrien Dupuis <61695653+adriendupuis@users.noreply.github.com>
|




Document built-in MCP Servers and how to create custom ones.
Also enhance the JWT documentation.
Related PRs:
vale: ibexa/vale-styles#40Checklist