The Istedlal MCP Server enables AI agents to manage file metadata, perform filtered searches, and run semantic searches over file embeddings.
Get File Metadata (get_file_metadata): Retrieve detailed metadata for a specific file by its ID, including filename, MIME type, file size, processing status, and storage information — scoped to a specific tenant and project.
Search Files by Metadata Filters (search_files): Query files using metadata-based filters such as filename, MIME type, processing status, and upload date range, with pagination support — scoped to a specific tenant and project.
Semantic Search Over Files (semantic_search_files): Perform natural language semantic search across file embeddings to find relevant content, with options to limit results (top_k), filter by specific file IDs, set a similarity score threshold, and scope the search to a specific tenant and project.
All operations support multi-tenant isolation via tenant and project identifiers. The server supports Docker/Kubernetes deployment, PostgreSQL + pgvector for vector storage, Ollama for embedding generation, Bearer token authentication, and multiple transport options (HTTP or stdio for IDE/Cursor integration).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Istedlal MCP Server search for files related to project budget using semantic search"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Server for Istedlal AI Agents - file metadata, vector search, workflow metrics access.
Python 3.10+
See requirements.txt for dependencies
Related MCP server: RagLit MCP Server
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
# Create .env with required variables (see docs/ENV_SETUP.md)Terminal testing (use streamable-http to avoid "Invalid JSON: EOF" errors):
# .env: MCP_TRANSPORT=streamable-http
python -m src.main
# Server at http://localhost:8000/mcpCursor/IDE integration (stdio - Cursor spawns the process, don't run manually):
# .env: MCP_TRANSPORT=stdio
# Add server to Cursor MCP settings; Cursor will start it automaticallyget_file_metadata - Fetch metadata for a file by ID (real DB when VECTOR_PROVIDER=pgvector)
search_files - Search files by metadata filters (real DB when pgvector)
semantic_search_files - Semantic search over file embeddings (Ollama + pgvector)
See docs/MCP_INSPECTOR_GUIDE.md for the complete step-by-step guide.
npx -y @modelcontextprotocol/inspectorItem | Required | Notes |
Dockerfile | Yes | Build container image |
.dockerignore | Yes | Exclude venv, .env, pycache |
Production .env | Yes | Set on server (never commit) |
Port 8000 | Yes | Expose for MCP endpoint |
PostgreSQL + pgvector | Phase 2 | document_metadata, document_embeddings (see data/vectordb_schema_documentation.pdf) |
Ollama | Phase 2 | For semantic search query embeddings |
.cursor/ – Cursor IDE config only, not needed on server
venv/ – Create fresh on server or use Docker
.env – Contains secrets; set separately on server
__pycache__/ – Python cache, auto-generated
data/ – Reference docs only, not runtime
MCP_TRANSPORT=streamable-http
HTTP_HOST=0.0.0.0
HTTP_PORT=8000
DATABASE_URL=postgresql://user:password@db-host:5432/dbname
VECTOR_PROVIDER=pgvector # mock | pgvector | chromadb
OLLAMA_URL=https://your-ollama:11433
OLLAMA_EMBEDDING_MODEL=llama3.2
OLLAMA_USERNAME= # if Basic Auth required
OLLAMA_PASSWORD=
LOG_LEVEL=INFO
MCP_BEARER_TOKEN=your-secret-token # Required – Bearer token auth for /mcpFROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY src/ ./src/
ENV MCP_TRANSPORT=streamable-http
ENV PYTHONUNBUFFERED=1
EXPOSE 8000
CMD ["python", "-m", "src.main"]venv/
.env
.git/
.cursor/
__pycache__/
*.pyc
data/
docs/
scripts/
tests/
infra/Build: docker build -t istedlal-mcp .
Run: docker run -p 8000:8000 -e DATABASE_URL=... -e MCP_BEARER_TOKEN=your-secret istedlal-mcp
Verify: curl http://localhost:8000/ (info page)
MCP Endpoint: http://your-server:8000/mcp
Use Deployment + Service manifests in infra/k8s/
Expose Service (ClusterIP/NodePort/LoadBalancer)
Set DATABASE_URL via Secret
Root / returns JSON with status
MCP endpoint: /mcp (for MCP clients only)
Logs: Set LOG_LEVEL=DEBUG for troubleshooting
Fetch metadata for a specific file by ID. Returns file details including filename, mime_type, size, processing_status, and storage info.
| Name | Required | Description | Default |
|---|---|---|---|
| file_id | Yes | ||
| tenant_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the return details (filename, mime_type, etc.), which is helpful, but fails to cover critical aspects like whether this is a read-only operation, potential error conditions (e.g., invalid ID), authentication needs, or rate limits. This leaves significant gaps for a tool with 3 required parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded, with two sentences that directly state the purpose and return details. There is no wasted text, making it efficient, though it could be slightly more structured by explicitly listing parameters or usage scenarios.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (3 required parameters, no annotations, no output schema), the description is incomplete. It covers the basic purpose and return fields but misses parameter semantics, behavioral traits like error handling, and lacks output schema details. This is inadequate for a tool with multiple required inputs and no structured safety hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate for all 3 parameters. It only mentions 'file_id' indirectly ('by ID'), but provides no context for 'tenant_id' or 'project_id', such as their roles or how they relate to the file. This adds minimal value beyond the schema, failing to clarify parameter meanings adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'fetch' and resource 'metadata for a specific file by ID', making the purpose evident. It distinguishes from siblings like 'search_files' by focusing on a single file rather than searching. However, it doesn't explicitly contrast with 'semantic_search_files', so it's not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'search_files' or 'semantic_search_files'. It implies usage for retrieving metadata of a known file ID, but lacks explicit when/when-not instructions or prerequisites, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search files using metadata filters. Supports filters like filename, mime_type, processing_status, upload date range.
| Name | Required | Description | Default |
|---|---|---|---|
| tenant_id | Yes | ||
| project_id | Yes | ||
| filters | No | ||
| page | No | ||
| page_size | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only mentions search functionality and filter examples. It lacks critical behavioral details: whether this is read-only, pagination behavior (implied by parameters but not described), rate limits, authentication needs, or what happens when no filters are provided. The description doesn't contradict annotations, but provides minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that efficiently convey core functionality and filter examples. It's front-loaded with the main purpose. No wasted words, though it could be slightly more structured with explicit parameter guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters with 0% schema coverage, no annotations, and no output schema, the description is incomplete. It covers the 'filters' parameter well but ignores others, lacks behavioral transparency for a search tool, and doesn't explain return values or error conditions. This leaves significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate but only partially does. It mentions 'metadata filters' and examples like 'filename, mime_type, processing_status, upload date range', which helps explain the 'filters' parameter. However, it doesn't address 'tenant_id', 'project_id', 'page', or 'page_size' parameters, leaving 4 of 5 parameters without semantic clarification.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('search') and resource ('files') with the method ('using metadata filters'). It distinguishes from 'get_file_metadata' by focusing on search rather than retrieval, and from 'semantic_search_files' by specifying metadata-based rather than semantic search. However, it doesn't explicitly name these distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'metadata filters' and example filters, suggesting when to use this tool. However, it doesn't explicitly state when to choose this over 'semantic_search_files' or 'get_file_metadata', nor does it mention prerequisites like required parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantic search over file embeddings. Use natural language to find relevant content across files.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| tenant_id | Yes | ||
| project_id | Yes | ||
| top_k | No | ||
| file_ids | No | ||
| threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions 'semantic search' and 'natural language', it doesn't describe how results are returned (e.g., relevance scores, format), whether it's read-only (implied but not stated), performance characteristics, or any limitations like rate limits or authentication needs. The description is too vague for a tool with 6 parameters and no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences that are front-loaded and waste no words. Every phrase ('Semantic search over file embeddings', 'Use natural language to find relevant content across files') directly contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 3 required), lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the tool returns, how to interpret results, or provide any details about parameter usage. For a search tool with multiple filtering options, this leaves significant gaps for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 6 parameters have descriptions in the schema. The tool description provides no information about parameters like 'tenant_id', 'project_id', 'top_k', 'file_ids', or 'threshold', leaving their purposes and usage completely undocumented. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Semantic search over file embeddings' with the specific action 'Use natural language to find relevant content across files.' It distinguishes itself from 'search_files' by specifying semantic search (natural language understanding) rather than keyword-based search, though it doesn't explicitly contrast with 'get_file_metadata'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('Use natural language to find relevant content') but doesn't explicitly state when to use this tool versus alternatives like 'search_files' or 'get_file_metadata'. It provides no guidance on prerequisites, exclusions, or specific scenarios where this tool is preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_file_metadatasearch_filessemantic_search_filesEach tool has a clearly distinct purpose: get_file_metadata retrieves specific file details by ID, search_files filters files based on explicit metadata criteria, and semantic_search_files finds files using natural language queries over embeddings. There is no overlap in functionality, making tool selection straightforward for an agent.
All tool names follow a consistent verb_noun pattern with snake_case: get_file_metadata, search_files, and semantic_search_files. The naming is predictable and readable, with no deviations in style or convention across the set.
With only 3 tools, the server feels thin for a file management domain, as it lacks essential operations like upload, delete, or update files. While the tools are well-defined, the count is borderline low for covering typical file lifecycle needs, potentially limiting agent workflows.
The tool set has significant gaps for file management: there are no tools for uploading, deleting, updating, or processing files, which are core operations in this domain. Agents will face dead ends when trying to perform basic file lifecycle tasks, as the surface only supports retrieval and search functions.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Securely search and manage workspace context files for AI agents and teams.
Ingest, manage, and retrieve documents for RAG-powered AI applications
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Document hosting and encrypted agent memory with multi-tenant persistence.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/AnshuML/MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
