IBX-11536: MCP Servers

[adriendupuis]

Question	Answer
JIRA Ticket	IBX-11068 > IBX-11536
Versions	5.0
Edition	All

Document built-in MCP Servers and how to create custom ones.
Also enhance the JWT documentation.

Related PRs:

• Release note: MCP release note #3170
• Fix JWT OpenAPI: JWT: The XML input and output aren't supported rest#217
• vale: ibexa/vale-styles#40

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• Redirects cover removed/moved pages
• Code samples are working
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/ai/ai.md
• docs/ai/mcp/mcp.md
• docs/ai/mcp/mcp_config.md
• docs/ai/mcp/mcp_guide.md
• docs/ai/mcp/mcp_usage.md
• docs/ai_actions/ai_actions.md
• docs/ai_actions/ai_actions_guide.md
• docs/ai_actions/configure_ai_actions.md
• docs/ai_actions/extend_ai_actions.md
• docs/api/api.md
• docs/api/graphql/graphql.md
• docs/api/rest_api/rest_api_authentication.md
• docs/ibexa_products/editions.md
• docs/infrastructure_and_maintenance/security/development_security.md
• docs/infrastructure_and_maintenance/security/security_checklist.md
• docs/product_guides/product_guides.md

Preview of addition to PHP API Reference:

• Ibexa\Contracts\Mcp
• Ibexa\Contracts\Mcp\Attribute
• Ibexa\Contracts\Mcp\Attribute\McpPrompt
• Ibexa\Contracts\Mcp\Attribute\McpResource
• Ibexa\Contracts\Mcp\Attribute\McpResourceTemplate
• Ibexa\Contracts\Mcp\Attribute\McpTool
• Ibexa\Contracts\Mcp\McpCapabilityInterface
• Ibexa\Contracts\Mcp\McpServerConfiguration
• Ibexa\Contracts\Mcp\McpServerConfigurationRegistryInterface

[mnocon]

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"

[barw4]

Awesome work 👏🏻

One more global comment, should we also document Resources like we did with Prompts?

[barw4]

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?

[adriendupuis]

Some LTS Update seem to have recipe entries. Maybe it can be done. It should be investigated.

[mnocon]

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

[barw4]

https://github.com/ibexa/mcp/pull/8 another tool by @bnowak in progress, something to keep an eye on

[adriendupuis]

https://github.com/ibexa/documentation-developer/pull/3196/changes

[barw4]

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?

[sonarqubecloud]

Quality Gate failed

Failed conditions
43.6% Duplication on New Code (required ≤ 3%)
C Reliability Rating on New Code (required ≥ A)
B Security Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

[github-actions]

code_samples/ change report

Before (on target branch)	After (in current PR)
code_samples/mcp/config/packages/mcp.yaml	code_samples/mcp/config/packages/mcp.yaml
	docs/ai/mcp/mcp_usage.md@78:``` yaml docs/ai/mcp/mcp_usage.md@79:[[= include_code('code_samples/mcp/config/packages/mcp.yaml') =]] docs/ai/mcp/mcp_usage.md@80:``` 001⫶ibexa: 002⫶ repositories: 003⫶ default: 004⫶ mcp: 005⫶ example: 006⫶ path: /mcp/example 007⫶ enabled: true 008⫶ description: 'Example MCP Server' 009⫶ instructions: 'Use this server to greet someone.' 010⫶ discovery_cache: cache.tagaware.filesystem 011⫶ session: 012⫶ type: psr16 013⫶ directory: cache.tagaware.filesystem 014⫶ system: 015⫶ default: 016⫶ mcp: 017⫶ servers: 018⫶ - example
code_samples/mcp/http.mcp.json	code_samples/mcp/http.mcp.json
	docs/ai/mcp/mcp_usage.md@277:``` json docs/ai/mcp/mcp_usage.md@278:[[= include_code('code_samples/mcp/http.mcp.json') =]] docs/ai/mcp/mcp_usage.md@279:``` 001⫶{ 002⫶ "mcpServers": { 003⫶ "ibexa-example": { 004⫶ "type": "http", 005⫶ "url": "http://localhost/mcp/example", 006⫶ "headers": { 007⫶ "Authorization": "Bearer <JWT token>" 008⫶ }, 009⫶ "tools": ["*"] 010⫶ } 011⫶ } 012⫶}
code_samples/mcp/mcp-ibexa-example-wrapper.sh	code_samples/mcp/mcp-ibexa-example-wrapper.sh
	docs/ai/mcp/mcp_usage.md@304:``` bash docs/ai/mcp/mcp_usage.md@305:[[= include_code('code_samples/mcp/mcp-ibexa-example-wrapper.sh') =]] docs/ai/mcp/mcp_usage.md@306:``` 001⫶#!/bin/bash 002⫶set -e 003⫶ 004⫶baseUrl='http://localhost' # Adapt to your test case 005⫶ 006⫶jwtToken=$(curl -s -X 'POST' \ 007⫶ "$baseUrl/api/ibexa/v2/user/token/jwt" \ 008⫶ -H 'Content-Type: application/vnd.ibexa.api.JWTInput+json' \ 009⫶ -H 'Accept: application/vnd.ibexa.api.JWT+json' \ 010⫶ -d '{ 011⫶ "JWTInput": { 012⫶ "_media-type": "application/vnd.ibexa.api.JWTInput+json", 013⫶ "username": "ibexa-example", 014⫶ "password": "Ibexa-3xample" 015⫶ } 016⫶ }' | jq -r .JWT.token) 017⫶ 018⫶exec npx -y supergateway \ 019⫶ --streamableHttp "$baseUrl/mcp/example" \ 020⫶ --oauth2Bearer "$jwtToken" \ 021⫶ --logLevel none
code_samples/mcp/mcp.matrix.yaml	code_samples/mcp/mcp.matrix.yaml
	docs/ai/mcp/mcp_config.md@54:``` yaml docs/ai/mcp/mcp_config.md@55:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 1, 8) =]] docs/ai/mcp/mcp_config.md@56:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 12, 15) =]] docs/ai/mcp/mcp_config.md@57:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 29, 33) =]] docs/ai/mcp/mcp_config.md@58:``` 001⫶ibexa: 002⫶ repositories: 003⫶ <repository_identifier>: 004⫶ mcp: 005⫶ <server_identifier>: 006⫶ path: <server_route_path> 007⫶ enabled: true 008⫶ # Server options… 009⫶ discovery_cache: <cache_pool_service> 010⫶ session: 011⫶ type: <psr16|file|memory> 012⫶ # Session options… 013⫶ system: 014⫶ <siteaccess_scope>: 015⫶ mcp: 016⫶ servers: 017⫶ - <server_identifier> docs/ai/mcp/mcp_config.md@105:``` yaml hl_lines="5-7" docs/ai/mcp/mcp_config.md@106:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 4, 7) =]] docs/ai/mcp/mcp_config.md@107:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 9, 11) =]] docs/ai/mcp/mcp_config.md@108: # … docs/ai/mcp/mcp_config.md@109:``` 001⫶ mcp: 002⫶ <server_identifier>: 003⫶ path: <server_route_path> 004⫶ enabled: true 005❇️ tools: 006❇️ - Ibexa\Mcp\Tool\TranslationTools 007❇️ - Ibexa\Mcp\Tool\SeoTools 008⫶ # … docs/ai/mcp/mcp_config.md@118:``` yaml docs/ai/mcp/mcp_config.md@119:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 17, 17) =]] docs/ai/mcp/mcp_config.md@120:``` 001⫶ discovery_cache: cache.redis.mcp docs/ai/mcp/mcp_config.md@153:``` yaml docs/ai/mcp/mcp_config.md@154:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 18, 21) =]] docs/ai/mcp/mcp_config.md@155:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 34, 43) =]] docs/ai/mcp/mcp_config.md@156:``` 001⫶ session: 002⫶ type: psr16 003⫶ service: cache.redis.mcp 004⫶ prefix: 'mcp_<server_identifier>_' 005⫶services: 006⫶ cache.redis.mcp: 007⫶ public: true 008⫶ class: Symfony\Component\Cache\Adapter\RedisTagAwareAdapter 009⫶ parent: cache.adapter.redis 010⫶ tags: 011⫶ - name: cache.pool 012⫶ clearer: cache.app_clearer 013⫶ provider: 'redis://mcp.redis:6379' 014⫶ namespace: 'mcp' docs/ai/mcp/mcp_config.md@167:``` yaml docs/ai/mcp/mcp_config.md@168:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 23, 25) =]] docs/ai/mcp/mcp_config.md@169:``` 001⫶ session: 002⫶ type: file 003⫶ directory: '%kernel.cache_dir%/mcp/sessions' docs/ai/mcp/mcp_config.md@177:``` yaml docs/ai/mcp/mcp_config.md@178:[[= include_code('code_samples/mcp/mcp.matrix.yaml', 27, 28) =]] docs/ai/mcp/mcp_config.md@179:``` 001⫶ session: 002⫶ type: memory
code_samples/mcp/mcp.sh	code_samples/mcp/mcp.sh
	docs/ai/mcp/mcp_usage.md@142:``` bash docs/ai/mcp/mcp_usage.md@143:[[= include_code('code_samples/mcp/mcp.sh', 5, 7) =]] docs/ai/mcp/mcp_usage.md@144:``` 001⫶baseUrl='http://localhost' # Adapt to your test case 002⫶username='ibexa-example' 003⫶password='Ibexa-3xample' docs/ai/mcp/mcp_usage.md@148:``` bash docs/ai/mcp/mcp_usage.md@149:[[= include_code('code_samples/mcp/mcp.sh', 9, 23) =]] docs/ai/mcp/mcp_usage.md@150:``` 001⫶curl -s -X 'POST' \ 002⫶ "$baseUrl/api/ibexa/v2/user/token/jwt" \ 003⫶ -H 'Content-Type: application/vnd.ibexa.api.JWTInput+json' \ 004⫶ -H 'Accept: application/vnd.ibexa.api.JWT+json' \ 005⫶ -d "{ 006⫶ \"JWTInput\": { 007⫶ \"_media-type\": \"application/vnd.ibexa.api.JWTInput+json\", 008⫶ \"username\": \"$username\", 009⫶ \"password\": \"$password\" 010⫶ } 011⫶ }" > response.tmp.txt 012⫶ 013⫶cat response.tmp.txt | jq 014⫶jwtToken=$(cat response.tmp.txt | jq -r .JWT.token) 015⫶rm response.tmp.txt docs/ai/mcp/mcp_usage.md@152:``` json docs/ai/mcp/mcp_usage.md@153:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 1, 7) =]] docs/ai/mcp/mcp_usage.md@154:``` 001⫶{ 002⫶ "JWT": { 003⫶ "_media-type": "application/vnd.ibexa.api.JWT+json", 004⫶ "_token": "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCD.EFGHIJKL-MNOPQRSTUVWXYZ12345678901234567890", 005⫶ "token": "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCD.EFGHIJKL-MNOPQRSTUVWXYZ12345678901234567890" 006⫶ } 007⫶} docs/ai/mcp/mcp_usage.md@158:``` bash docs/ai/mcp/mcp_usage.md@159:[[= include_code('code_samples/mcp/mcp.sh', 21, 44) =]] docs/ai/mcp/mcp_usage.md@160:``` 001⫶cat response.tmp.txt | jq 002⫶jwtToken=$(cat response.tmp.txt | jq -r .JWT.token) 003⫶rm response.tmp.txt 004⫶ 005⫶curl -s -i -X 'POST' "$baseUrl/mcp/example" \ 006⫶ -H "Authorization: Bearer $jwtToken" \ 007⫶ -d '{ 008⫶ "jsonrpc": "2.0", 009⫶ "id": 1, 010⫶ "method": "initialize", 011⫶ "params": { 012⫶ "protocolVersion": "2025-03-26", 013⫶ "capabilities": {}, 014⫶ "clientInfo": { 015⫶ "name": "test-curl-client", 016⫶ "version": "1.0.0" 017⫶ } 018⫶ } 019⫶ }' > response.tmp.txt 020⫶ 021⫶sed '$d' response.tmp.txt 022⫶tail -n 1 response.tmp.txt | jq 023⫶mcpSessionId=$(cat response.tmp.txt | grep 'Mcp-Session-Id:' | sed 's/Mcp-Session-Id: \([0-9a-f-]*\).*/\1/') 024⫶rm response.tmp.txt docs/ai/mcp/mcp_usage.md@162:``` http docs/ai/mcp/mcp_usage.md@163:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 8, 16) =]] docs/ai/mcp/mcp_usage.md@164:``` 001⫶HTTP/1.1 200 OK 002⫶Access-Control-Allow-Headers: Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, Authorization, Accept 003⫶Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS 004⫶Access-Control-Allow-Origin: * 005⫶Access-Control-Expose-Headers: Mcp-Session-Id 006⫶Cache-Control: no-cache, private 007⫶Content-Type: application/json 008⫶Date: Tue, 28 Apr 2026 09:53:27 GMT 009⫶Mcp-Session-Id: 12345678-9abc-def0-1234-56789abcdef0 docs/ai/mcp/mcp_usage.md@166:``` json docs/ai/mcp/mcp_usage.md@167:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 26, 51) =]] docs/ai/mcp/mcp_usage.md@168:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 1, 004⫶ "result": { 005⫶ "protocolVersion": "2025-06-18", 006⫶ "capabilities": { 007⫶ "logging": {}, 008⫶ "completions": {}, 009⫶ "prompts": { 010⫶ "listChanged": true 011⫶ }, 012⫶ "resources": { 013⫶ "listChanged": true 014⫶ }, 015⫶ "tools": { 016⫶ "listChanged": true 017⫶ } 018⫶ }, 019⫶ "serverInfo": { 020⫶ "name": "example", 021⫶ "version": "1.0.0", 022⫶ "description": "Example MCP Server" 023⫶ }, 024⫶ "instructions": "Use this server to greet someone." 025⫶ } 026⫶} docs/ai/mcp/mcp_usage.md@172:``` bash docs/ai/mcp/mcp_usage.md@173:[[= include_code('code_samples/mcp/mcp.sh', 46, 52) =]] docs/ai/mcp/mcp_usage.md@174:``` 001⫶curl -s -i -X 'POST' "$baseUrl/mcp/example" \ 002⫶ -H "Authorization: Bearer $jwtToken" \ 003⫶ -H "Mcp-Session-Id: $mcpSessionId" \ 004⫶ -d '{ 005⫶ "jsonrpc": "2.0", 006⫶ "method": "notifications/initialized" 007⫶ }' docs/ai/mcp/mcp_usage.md@176:``` http docs/ai/mcp/mcp_usage.md@177:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 52, 56) =]] docs/ai/mcp/mcp_usage.md@178:``` 001⫶HTTP/1.1 202 Accepted 002⫶Access-Control-Allow-Headers: Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, Authorization, Accept 003⫶Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS 004⫶Access-Control-Allow-Origin: * 005⫶Access-Control-Expose-Headers: Mcp-Session-Id docs/ai/mcp/mcp_usage.md@182:``` bash docs/ai/mcp/mcp_usage.md@183:[[= include_code('code_samples/mcp/mcp.sh', 54, 61) =]] docs/ai/mcp/mcp_usage.md@184:``` 001⫶curl -s -X 'POST' "$baseUrl/mcp/example" \ 002⫶ -H "Authorization: Bearer $jwtToken" \ 003⫶ -H "Mcp-Session-Id: $mcpSessionId" \ 004⫶ -d '{ 005⫶ "jsonrpc": "2.0", 006⫶ "id": 2, 007⫶ "method": "tools/list" 008⫶ }' | jq docs/ai/mcp/mcp_usage.md@186:``` json docs/ai/mcp/mcp_usage.md@187:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 69, 128) =]] docs/ai/mcp/mcp_usage.md@188:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 2, 004⫶ "result": { 005⫶ "tools": [ 006⫶ { 007⫶ "name": "greet", 008⫶ "inputSchema": { 009⫶ "type": "object", 010⫶ "properties": { 011⫶ "name": { 012⫶ "type": "string", 013⫶ "description": "The name of the person to greet" 014⫶ } 015⫶ }, 016⫶ "required": [ 017⫶ "name" 018⫶ ] 019⫶ }, 020⫶ "description": "Greet a user by name", 021⫶ "annotations": { 022⫶ "readOnlyHint": true, 023⫶ "destructiveHint": false, 024⫶ "idempotentHint": true, 025⫶ "openWorldHint": false 026⫶ }, 027⫶ "icons": [ 028⫶ { 029⫶ "src": "https://openmoji.org/data/color/svg/1F44B.svg" 030⫶ } 031⫶ ], 032⫶ "outputSchema": { 033⫶ "type": "object", 034⫶ "properties": { 035⫶ "general": { 036⫶ "type": "string", 037⫶ "description": "the safe way to greet someone" 038⫶ }, 039⫶ "close": { 040⫶ "type": "string", 041⫶ "description": "when you're close to the person, like friends or relatives" 042⫶ }, 043⫶ "morning": { 044⫶ "type": "string", 045⫶ "description": "when it's in the morning" 046⫶ }, 047⫶ "afternoon": { 048⫶ "type": "string", 049⫶ "description": "when it's the afternoon" 050⫶ }, 051⫶ "evening": { 052⫶ "type": "string", 053⫶ "description": "when it's late in the day" 054⫶ } 055⫶ } 056⫶ } 057⫶ } 058⫶ ] 059⫶ } 060⫶} docs/ai/mcp/mcp_usage.md@192:``` bash docs/ai/mcp/mcp_usage.md@193:[[= include_code('code_samples/mcp/mcp.sh', 63, 76) =]] docs/ai/mcp/mcp_usage.md@194:``` 001⫶curl -s -X 'POST' "$baseUrl/mcp/example" \ 002⫶ -H "Authorization: Bearer $jwtToken" \ 003⫶ -H "Mcp-Session-Id: $mcpSessionId" \ 004⫶ -d '{ 005⫶ "jsonrpc": "2.0", 006⫶ "id": 3, 007⫶ "method": "tools/call", 008⫶ "params": { 009⫶ "name": "greet", 010⫶ "arguments": { 011⫶ "name": "World" 012⫶ } 013⫶ } 014⫶ }' | jq docs/ai/mcp/mcp_usage.md@196:``` json docs/ai/mcp/mcp_usage.md@197:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 129, 148) =]] docs/ai/mcp/mcp_usage.md@198:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 3, 004⫶ "result": { 005⫶ "content": [ 006⫶ { 007⫶ "type": "text", 008⫶ "text": "{\n \"general\": \"Hello, World!\",\n \"close\": \"Hey, World!\",\n \"morning\": \"Good morning, World!\",\n \"afternoon\": \"Good afternoon, World!\",\n \"evening\": \"Good evening, World!\"\n}" 009⫶ } 010⫶ ], 011⫶ "isError": false, 012⫶ "structuredContent": { 013⫶ "general": "Hello, World!", 014⫶ "close": "Hey, World!", 015⫶ "morning": "Good morning, World!", 016⫶ "afternoon": "Good afternoon, World!", 017⫶ "evening": "Good evening, World!" 018⫶ } 019⫶ } 020⫶} docs/ai/mcp/mcp_usage.md@202:``` bash docs/ai/mcp/mcp_usage.md@203:[[= include_code('code_samples/mcp/mcp.sh', 78, 85) =]] docs/ai/mcp/mcp_usage.md@204:``` 001⫶curl -s -X 'POST' "$baseUrl/mcp/example" \ 002⫶ -H "Authorization: Bearer $jwtToken" \ 003⫶ -H "Mcp-Session-Id: $mcpSessionId" \ 004⫶ -d '{ 005⫶ "jsonrpc": "2.0", 006⫶ "id": 4, 007⫶ "method": "prompts/list" 008⫶ }' | jq docs/ai/mcp/mcp_usage.md@206:``` json docs/ai/mcp/mcp_usage.md@207:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 149, 172) =]] docs/ai/mcp/mcp_usage.md@208:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 4, 004⫶ "result": { 005⫶ "prompts": [ 006⫶ { 007⫶ "name": "greet", 008⫶ "description": "Prompt to be greeted by the `greet` tool", 009⫶ "arguments": [ 010⫶ { 011⫶ "name": "name", 012⫶ "description": "The name you want to be greeted by", 013⫶ "required": true 014⫶ } 015⫶ ], 016⫶ "icons": [ 017⫶ { 018⫶ "src": "https://openmoji.org/data/color/svg/1F91D.svg" 019⫶ } 020⫶ ] 021⫶ } 022⫶ ] 023⫶ } 024⫶} docs/ai/mcp/mcp_usage.md@212:``` bash docs/ai/mcp/mcp_usage.md@213:[[= include_code('code_samples/mcp/mcp.sh', 87, 100) =]] docs/ai/mcp/mcp_usage.md@214:``` 001⫶curl -s -X 'POST' "$baseUrl/mcp/example" \ 002⫶ -H "Authorization: Bearer $jwtToken" \ 003⫶ -H "Mcp-Session-Id: $mcpSessionId" \ 004⫶ -d '{ 005⫶ "jsonrpc": "2.0", 006⫶ "id": 5, 007⫶ "method": "prompts/get", 008⫶ "params": { 009⫶ "name": "greet", 010⫶ "arguments": { 011⫶ "name": "Firstname Lastname" 012⫶ } 013⫶ } 014⫶ }' | jq docs/ai/mcp/mcp_usage.md@216:``` json docs/ai/mcp/mcp_usage.md@217:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 173, 187) =]] docs/ai/mcp/mcp_usage.md@218:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 5, 004⫶ "result": { 005⫶ "messages": [ 006⫶ { 007⫶ "role": "user", 008⫶ "content": { 009⫶ "type": "text", 010⫶ "text": "Hi. My name is Firstname Lastname. Please, greet me." 011⫶ } 012⫶ } 013⫶ ] 014⫶ } 015⫶}
code_samples/mcp/mcp.sh.output.txt	code_samples/mcp/mcp.sh.output.txt
	docs/ai/mcp/mcp_usage.md@152:``` json docs/ai/mcp/mcp_usage.md@153:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 1, 7) =]] docs/ai/mcp/mcp_usage.md@154:``` 001⫶{ 002⫶ "JWT": { 003⫶ "_media-type": "application/vnd.ibexa.api.JWT+json", 004⫶ "_token": "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCD.EFGHIJKL-MNOPQRSTUVWXYZ12345678901234567890", 005⫶ "token": "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ.abcdefghijklmnopqrstuvwxyz1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz1234567890ABCD.EFGHIJKL-MNOPQRSTUVWXYZ12345678901234567890" 006⫶ } 007⫶} docs/ai/mcp/mcp_usage.md@162:``` http docs/ai/mcp/mcp_usage.md@163:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 8, 16) =]] docs/ai/mcp/mcp_usage.md@164:``` 001⫶HTTP/1.1 200 OK 002⫶Access-Control-Allow-Headers: Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, Authorization, Accept 003⫶Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS 004⫶Access-Control-Allow-Origin: * 005⫶Access-Control-Expose-Headers: Mcp-Session-Id 006⫶Cache-Control: no-cache, private 007⫶Content-Type: application/json 008⫶Date: Tue, 28 Apr 2026 09:53:27 GMT 009⫶Mcp-Session-Id: 12345678-9abc-def0-1234-56789abcdef0 docs/ai/mcp/mcp_usage.md@166:``` json docs/ai/mcp/mcp_usage.md@167:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 26, 51) =]] docs/ai/mcp/mcp_usage.md@168:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 1, 004⫶ "result": { 005⫶ "protocolVersion": "2025-06-18", 006⫶ "capabilities": { 007⫶ "logging": {}, 008⫶ "completions": {}, 009⫶ "prompts": { 010⫶ "listChanged": true 011⫶ }, 012⫶ "resources": { 013⫶ "listChanged": true 014⫶ }, 015⫶ "tools": { 016⫶ "listChanged": true 017⫶ } 018⫶ }, 019⫶ "serverInfo": { 020⫶ "name": "example", 021⫶ "version": "1.0.0", 022⫶ "description": "Example MCP Server" 023⫶ }, 024⫶ "instructions": "Use this server to greet someone." 025⫶ } 026⫶} docs/ai/mcp/mcp_usage.md@176:``` http docs/ai/mcp/mcp_usage.md@177:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 52, 56) =]] docs/ai/mcp/mcp_usage.md@178:``` 001⫶HTTP/1.1 202 Accepted 002⫶Access-Control-Allow-Headers: Content-Type, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID, Authorization, Accept 003⫶Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS 004⫶Access-Control-Allow-Origin: * 005⫶Access-Control-Expose-Headers: Mcp-Session-Id docs/ai/mcp/mcp_usage.md@186:``` json docs/ai/mcp/mcp_usage.md@187:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 69, 128) =]] docs/ai/mcp/mcp_usage.md@188:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 2, 004⫶ "result": { 005⫶ "tools": [ 006⫶ { 007⫶ "name": "greet", 008⫶ "inputSchema": { 009⫶ "type": "object", 010⫶ "properties": { 011⫶ "name": { 012⫶ "type": "string", 013⫶ "description": "The name of the person to greet" 014⫶ } 015⫶ }, 016⫶ "required": [ 017⫶ "name" 018⫶ ] 019⫶ }, 020⫶ "description": "Greet a user by name", 021⫶ "annotations": { 022⫶ "readOnlyHint": true, 023⫶ "destructiveHint": false, 024⫶ "idempotentHint": true, 025⫶ "openWorldHint": false 026⫶ }, 027⫶ "icons": [ 028⫶ { 029⫶ "src": "https://openmoji.org/data/color/svg/1F44B.svg" 030⫶ } 031⫶ ], 032⫶ "outputSchema": { 033⫶ "type": "object", 034⫶ "properties": { 035⫶ "general": { 036⫶ "type": "string", 037⫶ "description": "the safe way to greet someone" 038⫶ }, 039⫶ "close": { 040⫶ "type": "string", 041⫶ "description": "when you're close to the person, like friends or relatives" 042⫶ }, 043⫶ "morning": { 044⫶ "type": "string", 045⫶ "description": "when it's in the morning" 046⫶ }, 047⫶ "afternoon": { 048⫶ "type": "string", 049⫶ "description": "when it's the afternoon" 050⫶ }, 051⫶ "evening": { 052⫶ "type": "string", 053⫶ "description": "when it's late in the day" 054⫶ } 055⫶ } 056⫶ } 057⫶ } 058⫶ ] 059⫶ } 060⫶} docs/ai/mcp/mcp_usage.md@196:``` json docs/ai/mcp/mcp_usage.md@197:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 129, 148) =]] docs/ai/mcp/mcp_usage.md@198:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 3, 004⫶ "result": { 005⫶ "content": [ 006⫶ { 007⫶ "type": "text", 008⫶ "text": "{\n \"general\": \"Hello, World!\",\n \"close\": \"Hey, World!\",\n \"morning\": \"Good morning, World!\",\n \"afternoon\": \"Good afternoon, World!\",\n \"evening\": \"Good evening, World!\"\n}" 009⫶ } 010⫶ ], 011⫶ "isError": false, 012⫶ "structuredContent": { 013⫶ "general": "Hello, World!", 014⫶ "close": "Hey, World!", 015⫶ "morning": "Good morning, World!", 016⫶ "afternoon": "Good afternoon, World!", 017⫶ "evening": "Good evening, World!" 018⫶ } 019⫶ } 020⫶} docs/ai/mcp/mcp_usage.md@206:``` json docs/ai/mcp/mcp_usage.md@207:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 149, 172) =]] docs/ai/mcp/mcp_usage.md@208:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 4, 004⫶ "result": { 005⫶ "prompts": [ 006⫶ { 007⫶ "name": "greet", 008⫶ "description": "Prompt to be greeted by the `greet` tool", 009⫶ "arguments": [ 010⫶ { 011⫶ "name": "name", 012⫶ "description": "The name you want to be greeted by", 013⫶ "required": true 014⫶ } 015⫶ ], 016⫶ "icons": [ 017⫶ { 018⫶ "src": "https://openmoji.org/data/color/svg/1F91D.svg" 019⫶ } 020⫶ ] 021⫶ } 022⫶ ] 023⫶ } 024⫶} docs/ai/mcp/mcp_usage.md@216:``` json docs/ai/mcp/mcp_usage.md@217:[[= include_code('code_samples/mcp/mcp.sh.output.txt', 173, 187) =]] docs/ai/mcp/mcp_usage.md@218:``` 001⫶{ 002⫶ "jsonrpc": "2.0", 003⫶ "id": 5, 004⫶ "result": { 005⫶ "messages": [ 006⫶ { 007⫶ "role": "user", 008⫶ "content": { 009⫶ "type": "text", 010⫶ "text": "Hi. My name is Firstname Lastname. Please, greet me." 011⫶ } 012⫶ } 013⫶ ] 014⫶ } 015⫶}
code_samples/mcp/src/Command/McpServerListCommand.php	code_samples/mcp/src/Command/McpServerListCommand.php
	docs/ai/mcp/mcp_usage.md@124:``` php docs/ai/mcp/mcp_usage.md@125:[[= include_code('code_samples/mcp/src/Command/McpServerListCommand.php') =]] docs/ai/mcp/mcp_usage.md@126:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\Command; 004⫶ 005⫶use Ibexa\Contracts\Mcp\McpServerConfigurationRegistryInterface; 006⫶use Symfony\Component\Console\Attribute\AsCommand; 007⫶use Symfony\Component\Console\Command\Command; 008⫶use Symfony\Component\Console\Style\SymfonyStyle; 009⫶ 010⫶#[AsCommand(name: 'app:mcp:server_list', description: 'List MCP servers')] 011⫶class McpServerListCommand 012⫶{ 013⫶ public function __construct(private readonly McpServerConfigurationRegistryInterface $configRegistry) 014⫶ { 015⫶ } 016⫶ 017⫶ public function __invoke(SymfonyStyle $io): int 018⫶ { 019⫶ foreach($this->configRegistry->getServerConfigurations() as $serverConfiguration) { 020⫶ $io->title($serverConfiguration->identifier); 021⫶ dump($serverConfiguration); 022⫶ } 023⫶ 024⫶ return Command::SUCCESS; 025⫶ } 026⫶}
code_samples/mcp/src/Mcp/ExampleCapabilities.php	code_samples/mcp/src/Mcp/ExampleCapabilities.php
	docs/ai/mcp/mcp_usage.md@96:``` php docs/ai/mcp/mcp_usage.md@97:[[= include_code('code_samples/mcp/src/Mcp/ExampleCapabilities.php') =]] docs/ai/mcp/mcp_usage.md@98:``` 001⫶<?php declare(strict_types=1); 002⫶ 003⫶namespace App\Mcp; 004⫶ 005⫶use Ibexa\Contracts\Mcp\Attribute\McpPrompt; 006⫶use Ibexa\Contracts\Mcp\Attribute\McpTool; 007⫶use Ibexa\Contracts\Mcp\McpCapabilityInterface; 008⫶use Mcp\Schema\Icon; 009⫶use Mcp\Schema\ToolAnnotations; 010⫶ 011⫶final readonly class ExampleCapabilities implements McpCapabilityInterface 012⫶{ 013⫶ /** 014⫶ * @param string $name The name of the person to greet 015⫶ * 016⫶ * @return array<string, string> 017⫶ */ 018⫶ #[McpTool( 019⫶ servers: ['example'], 020⫶ name: 'greet', 021⫶ description: 'Greet a user by name', 022⫶ annotations: new ToolAnnotations( 023⫶ readOnlyHint: true, 024⫶ destructiveHint: false, 025⫶ idempotentHint: true, 026⫶ openWorldHint: false, 027⫶ ), 028⫶ icons: [new Icon( 029⫶ src: 'https://openmoji.org/data/color/svg/1F44B.svg', 030⫶ )], 031⫶ outputSchema: [ 032⫶ 'type' => 'object', 033⫶ 'properties' => [ 034⫶ 'general' => [ 035⫶ 'type' => 'string', 036⫶ 'description' => 'the safe way to greet someone', 037⫶ ], 038⫶ 'close' => [ 039⫶ 'type' => 'string', 040⫶ 'description' => 'when you\'re close to the person, like friends or relatives', 041⫶ ], 042⫶ 'morning' => [ 043⫶ 'type' => 'string', 044⫶ 'description' => 'when it\'s in the morning', 045⫶ ], 046⫶ 'afternoon' => [ 047⫶ 'type' => 'string', 048⫶ 'description' => 'when it\'s the afternoon', 049⫶ ], 050⫶ 'evening' => [ 051⫶ 'type' => 'string', 052⫶ 'description' => 'when it\'s late in the day', 053⫶ ], 054⫶ ], 055⫶ ], 056⫶ )] 057⫶ public function greetByName(string $name): array 058⫶ { 059⫶ return [ 060⫶ 'general' => sprintf('Hello, %s!', $name), 061⫶ 'close' => sprintf('Hey, %s!', $name), 062⫶ 'morning' => sprintf('Good morning, %s!', $name), 063⫶ 'afternoon' => sprintf('Good afternoon, %s!', $name), 064⫶ 'evening' => sprintf('Good evening, %s!', $name), 065⫶ ]; 066⫶ } 067⫶ 068⫶ /** 069⫶ * @param string $name The name you want to be greeted by 070⫶ * 071⫶ * @return array<string, mixed> 072⫶ */ 073⫶ #[McpPrompt( 074⫶ servers: ['example'], 075⫶ name: 'greet', 076⫶ description: 'Prompt to invoke the `greet` tool', 077⫶ icons: [new Icon( 078⫶ src: 'https://openmoji.org/data/color/svg/1F91D.svg', 079⫶ )], 080⫶ )] 081⫶ public function getGreetPrompt(string $name): array 082⫶ { 083⫶ return [ 084⫶ 'role' => 'user', 085⫶ 'content' => [ 086⫶ 'type' => 'text', 087⫶ 'text' => "Hi. My name is $name. Please, greet me.", 088⫶ ], 089⫶ ]; 090⫶ } 091⫶}
code_samples/mcp/stdio.mcp.json	code_samples/mcp/stdio.mcp.json
	docs/ai/mcp/mcp_usage.md@296:``` json docs/ai/mcp/mcp_usage.md@297:[[= include_code('code_samples/mcp/stdio.mcp.json') =]] docs/ai/mcp/mcp_usage.md@298:``` 001⫶{ 002⫶ "mcpServers": { 003⫶ "ibexa-example": { 004⫶ "type": "stdio", 005⫶ "command": "bash", 006⫶ "args": ["mcp-ibexa-example-wrapper.sh"], 007⫶ "tools": ["*"] 008⫶ } 009⫶ } 010⫶}

Download colorized diff