MCP Channel
Connect your AI coding assistant to IdentityScribe and query identity data, discover schemas, and monitor system health—directly from your IDE.
Overview
Section titled “Overview”IdentityScribe exposes two MCP servers:
| Endpoint | Purpose | Tools |
|---|---|---|
/mcp | Data — Schema discovery, entry search, history, documentation | describe, search, lookup, changes, help, ref |
/observe/mcp | Observe — System health, status, diagnostics | observe |
Works with: Cursor, Claude Desktop, VS Code, Windsurf, Codex, Gemini CLI, Goose, and any MCP-compatible client.
Related:
- Configuration Reference — all settings, env vars, and defaults
- Channels Overview — general channel concepts
- REST Channel — HTTP/JSON alternative
- GraphQL Channel — flexible query API
Quick start
Section titled “Quick start”Enable the MCP channels:
# Data MCP at /mcpexport SCRIBE_MCP_ENABLED=true
# Observe MCP at /observe/mcp (optional)export SCRIBE_MONITORING_MCP_ENABLED=trueThen configure your AI client to connect.
What you can ask
Section titled “What you can ask”Once connected, your AI assistant can query identity data and check system health. Just ask in plain English.
Working with identity data
Section titled “Working with identity data”Explore the schema
“What entry types are in the directory?”
“Show me the user attributes”
“What fields does the Group type have?”
Find entries
“Find users with @acme.com email addresses”
“Show me all groups that contain ‘admin’ in the name”
“List the first 50 roles”
Look up a specific entry
“Get the user with ID dXNlcjo5aXg”
“Show me the entry with DN cn=john,ou=users,dc=example,dc=com”
“What did user 12345 look like yesterday?” (point-in-time lookup)
View change history
“What changed in the last 24 hours?”
“Show me the history for user dXNlcjo5aXg”
“What attributes were modified on this entry?”
Filter syntax help
If you’re building filters manually, ask for help:
“How do I write a filter to find users created after January 2024?”
“What filter syntax does IdentityScribe support?”
Look up reference docs
“What does error SCRIBE-1001 mean?”
“Tell me about the scribe.query.duration metric”
Monitoring and diagnostics
Section titled “Monitoring and diagnostics”Check system health
“Is the system healthy?”
“What’s the current status?”
“Are all services running?”
Diagnose issues
“Run diagnostics”
“What’s wrong with the system?”
“Check for any problems”
View performance metrics
“Show me the error rates”
“What’s the query latency?”
“How many requests per second are we handling?”
Check configuration
“What channels are enabled?”
“Show me the current channel bindings”
Available resources
Section titled “Available resources”The Data MCP exposes these resources for AI agents to access schemas and documentation:
| URI | Description |
|---|---|
scribe://openapi | OpenAPI 3.1 specification (JSON) |
scribe://graphql-schema | GraphQL schema (SDL) |
scribe://ref-index | Reference documentation index (JSON) |
Configuration
Section titled “Configuration”Data MCP (/mcp)
Section titled “Data MCP (/mcp)”# EnableSCRIBE_MCP_ENABLED=true
# Bind to specific socket(s) — optionalSCRIBE_MCP_SOCKET=admin,internal
# Query limitsSCRIBE_MCP_DEFAULT_LIMIT=25SCRIBE_MCP_MAX_LIMIT=100Observe MCP (/observe/mcp)
Section titled “Observe MCP (/observe/mcp)”# EnableSCRIBE_MONITORING_MCP_ENABLED=true
# Bind to specific socket(s) — optionalSCRIBE_MONITORING_MCP_SOCKET=adminProtocol requirements
Section titled “Protocol requirements”Troubleshooting
Section titled “Troubleshooting”Connection refused
Section titled “Connection refused”- Check IdentityScribe is running:
curl http://localhost:8080/observe/health - Verify MCP is enabled in config
- Confirm the URL in your client matches the server address
Tools not working
Section titled “Tools not working”- Check the MCP channel is enabled (
SCRIBE_MCP_ENABLED=true) - Restart your AI client after config changes
- Try asking “What tools are available?” to verify connection
Slow responses
Section titled “Slow responses”Large result sets are automatically paginated. If you need more results, ask:
“Show me the next page of results”
“Get 100 users instead of 25”
500 errors on SSE/streaming
Section titled “500 errors on SSE/streaming”If you see HTTP 500 errors when connecting, check that HTTP/1.1 is enabled on the socket:
http.protocols.http-1-1.enabled = trueMCP uses Server-Sent Events (SSE) which requires HTTP/1.1. HTTP/2-only sockets will fail.
Still stuck?
Section titled “Still stuck?”Ask your AI assistant directly:
“What does error SCRIBE-1001 mean?”
“Help me understand this error”
The ref tool can look up any error code, metric, or config key from the reference documentation.