Click on "Deploy 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., "@Rasdaman MCP Server List all coverages"
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.
This tool enables users to interact with rasdaman in a natural language context. By exposing rasdaman functionality as tools via the MCP protocol, an LLM can query the database to answer questions like:
"What datacubes are available?"
"What are the dimensions of the 'Sentinel2_10m' coverage?"
"Create an NDVI image for June 12, 2025."
The MCP server translates these tool calls into actual WCS/WCPS queries that rasdaman can understand and then returns the results to the LLM.
pip install rasdaman-mcpRelated MCP server: 3DCityDB MCP Server
The entry point is rasdaman-mcp. It can be run in two primary modes controlled by the --transport command-line argument: stdio (default) and http.
The connection from the MCP server to rasdaman can be configured in two ways.
Command-line arguments:
--rasdaman-url: URL for the rasdaman server (default RASDAMAN_URL environment variable or http://localhost:8080/rasdaman/ows).
--username: Username for authentication (default RASDAMAN_USERNAME environment variable or rasguest).
--password: Sets the password for authentication (default RASDAMAN_PASSWORD environment variable or rasguest).
Environment variables:
RASDAMAN_URL: URL for the rasdaman server
RASDAMAN_USERNAME: Username for authentication
RASDAMAN_PASSWORD: Password for authentication
stdio ModeUsed for direct integration with clients that take over managing the server process. It uses standard input/output for communication. Generally in your client configuration you need to specify the command to run the MCP tool:
rasdaman-mcp --username rasguest --password rasguestKeep in mind that all dependencies are installed, and the venv is activated if necessary.
Example for gemini-cli:
gemini mcp add rasdaman-mcp "rasdaman-mcp --username rasguest --password rasguest"Benefits:
Simplicity: No need to manage a separate server process or ports.
Seamless Integration: Tools are transparently made available to the LLM within the client environment.
http ModeThis mode runs a standalone Web server.
Start the server:
rasdaman-mcp --transport http --host 127.0.0.1 --port 8000 --rasdaman-url "http://localhost:8080/rasdaman/ows"
Configure your client to add an MCP server at http://127.0.0.1:8000/mcp. For example, for
Mistral Vibe extend the config.toml with a section like this:
[[mcp_servers]]
name = "rasdaman-mcp"
transport = "streamable-http"
url = "http://127.0.0.1:8000/mcp/"Benefits:
Scalability: The MCP server can be containerized (e.g., with Docker) and deployed as a separate microservice.
Decoupling: Any client that can speak HTTP (e.g., curl, Python scripts, web apps, other LLM clients) can interact with the tools.
Testing: Allows for direct API testing and debugging, independent of an LLM client.
Clone the git repository:
git clone https://github.com/rasdaman/rasdaman-mcp.git
cd rasdaman-mcp/Create a virtual environment (if you don't have one):
uv venvActivate the virtual environment:
source .venv/bin/activateInstall from source:
uv pip install -e .Main Application (main.py): This script initializes the FastMCP application. It handles command-line arguments for transport selection, rasdaman URL,
username, and password. It then instantiates the RasdamanActions class and decorates its methods to expose them as tools.
RasdamanActions Class (rasdaman_actions.py): Encapsulates all interaction with the rasdaman WCS/WCPS endpoints.
It is initialized with the server URL and credentials, and its methods contain the logic for listing coverages, describing them, and executing queries.
WCPS crash course (wcps_crash_course.py): A short summary of the syntax of WCPS, allowing LLMs to generate more accurate queries.
WCPS query validation (query_validator.py): Throws a SyntaxError if a WCPS query has invalid syntax, allowing LLMs to locally validate query syntax.
The following methods are exposed as tools:
list_coverages(): Lists all available datacubes.
describe_coverage(coverage_id): Retrieves metadata for a specific datacube.
wcps_query_crash_course(): Returns a crash course on WCPS syntax with examples and best practices.
validate_wcps_query(wcps_query): Validates the syntax of a WCPS query without executing it.
execute_wcps_query(wcps_query): Executes a raw WCPS query and returns a result either directly as a string (scalars or small json), or as a filepath.
To build the documentation:
# install dependencies
uv pip install '.[docs]'
sphinx-build docs docs/_buildYou can then open docs/_build/index.html in the browser.
To run the tests:
# install dependencies
uv pip install '.[tests]'
pytestInteracting with the standalone HTTP server manually requires a specific 3-step process using curl.
The fastmcp protocol is stateful and requires a session to be explicitly initialized.
First, send an initialize request. This will return a 200 OK response and, most importantly,
a session ID in the mcp-session-id response header (needed in the next steps).
curl -i -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": { "name": "curl-client", "version": "1.0.0" }
},
"id": 1
}' \
"http://127.0.0.1:8000/mcp"Next, send a notification to the server to confirm the session is ready. Use the session ID from Step 1 in the mcp-session-id header.
This request will not produce a body in the response.
SESSION_ID="<YOUR_SESSION_ID>"
curl -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"method": "notifications/initialized"
}' \
"http://127.0.0.1:8000/mcp"Finally, you can call a tool using the tools/call method. The params object must contain the name of the tool and
an arguments object with the parameters for that tool. The server will respond with the result of the tool call in a JSON-RPC response.
SESSION_ID="<YOUR_SESSION_ID>"
# Example: Calling the 'list_coverages' tool
curl -X POST \
-H "Accept: text/event-stream, application/json" \
-H "Content-Type: application/json" \
-H "Mcp-Session-Id: $SESSION_ID" \
-d '{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"name": "list_coverages",
"arguments": {}
},
"id": 2
}' \
"http://127.0.0.1:8000/mcp"Retrieves structural metadata for a specific datacube (coverage).
| Name | Required | Description | Default |
|---|---|---|---|
| coverage_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implies a read-only operation but fails to detail potential side effects, error handling, or response characteristics (e.g., no mention of what happens if coverage_id is invalid). The description is too minimal to provide adequate transparency.
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 a single sentence, concise and to the point. It avoids unnecessary words. However, a more structured format (e.g., bullet points) could improve readability for agents, but overall it is appropriately sized.
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?
The tool is simple with one parameter and an output schema (which may mitigate the need for extensive return value description). However, the description does not explain what 'structural metadata' includes or any context like typical use cases. It is minimally adequate for a simple tool but lacks depth.
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 the description must compensate for parameter meaning. However, the description only mentions 'specific datacube' without clarifying the format, constraints, or examples for 'coverage_id'. The parameter semantics are largely left to inference.
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 'retrieves' and the resource 'structural metadata for a specific datacube (coverage)'. It distinguishes from siblings like 'list_coverages' which lists coverages, and 'execute_wcps_query' which runs queries. However, it is somewhat vague about what constitutes 'structural metadata', leaving room for ambiguity.
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?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like 'list_coverages' or 'execute_wcps_query'. There is no mention of prerequisites or context for optimal use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Executes a Web Coverage Processing Service (WCPS) query in rasdaman. Use this for spatio-temporal subsetting of datacubes, processing, aggregation, or filtering. If the query returns binary data (e.g., an image or NetCDF file), the tool saves it to a temporary file and return the path. Important: Show the actual WCPS query and the result file path to the user.
| Name | Required | Description | Default |
|---|---|---|---|
| wcps_query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions that binary data results are saved to a temporary file and the path is returned, and instructs to show the query and path to the user. However, it does not disclose error behavior, side effects (e.g., whether queries can modify data), permissions required, or rate limits.
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?
Three sentences with no redundancy: first states purpose, second lists use cases, third explains binary handling and user instruction. Structure is logical and front-loaded.
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 tool's complexity (query execution), the description covers core functionality and binary handling but lacks output format, error behavior, and permissions. The instruction to show the query and path is helpful but not core behavioral context. Adequate but with clear gaps.
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 single parameter 'wcps_query' has 0% schema description coverage. The description merely calls it 'the WCPS query' without providing syntax, examples, or constraints. The sibling validate_wcps_query could serve as a reference, but the description does not connect to it.
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 it executes a WCPS query in rasdaman and lists specific uses like subsetting, processing, aggregation, and filtering. This distinguishes it from siblings (describe_coverage, list_coverages, validate_wcps_query, wcps_query_crash_course) which have different purposes.
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 suggests when to use the tool ('for spatio-temporal subsetting...') but does not explicitly state when not to use it or mention alternatives (e.g., using validate_wcps_query for validation). The guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists all available datacubes (coverages) in rasdaman.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It adequately states the tool lists all available coverages, but does not mention any behavioral aspects like authorization requirements, performance, or the nature of 'available'.
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?
Single sentence, perfectly concise and front-loaded. No wasted words.
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 no parameters and existence of output schema, the description is mostly complete. It could mention that the output provides coverage names for use with other tools, but this is not essential.
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?
Input schema has no parameters (0 params), so baseline is 4. Description does not need to add param info because none exist.
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?
Clearly states it lists all available datacubes/coverages in rasdaman, with a specific verb and resource. Distinguishes from sibling tools like describe_coverage and execute_wcps_query which serve different purposes.
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?
No explicit guidance on when to use this tool versus siblings. The context implies it could be used to discover coverages before describing or querying, but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use this to check if your WCPS query is syntactically correct before execution. Returns "VALID" if the query syntax is correct, or "INVALID SYNTAX: " otherwise.
| Name | Required | Description | Default |
|---|---|---|---|
| wcps_query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description fully discloses behavior: returns 'VALID' or 'INVALID SYNTAX: <error>'. It is a read-only validation with no side effects mentioned.
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?
Two sentences, front-loaded with usage guidance followed by return format. No unnecessary words.
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?
For a one-parameter validation tool with output schema present, description covers usage context, return values, and relationship to siblings. No gaps.
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?
Only one parameter (wcps_query) with 0% schema description coverage. The description implies it is the query string but does not elaborate on format or constraints. Adequate for a simple tool.
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 validates WCPS query syntax, using specific verb 'check' and resource 'query'. It distinguishes from sibling tools like execute_wcps_query which runs the query.
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?
Explicitly says to use 'before execution', giving clear context. Does not list when not to use, but the sibling execute_wcps_query implies the alternative for running queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a crash course on writing WCPS queries: learn the basic syntax, common operations, and best practices for WCPS queries. It's recommended to check this before executing queries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses that the tool returns educational content with no side effects, making its behavior transparent.
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?
Two sentences that front-load the purpose and add a recommendation, with no wasted words.
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?
For a simple informational tool with no parameters, the description fully explains what it returns and why to use it, and the output schema presumably covers structure.
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?
No parameters exist, so baseline is 4. Description adds no parameter info, which is fine given 100% schema coverage and zero parameters.
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 it returns a crash course on WCPS queries, distinguishing it from sibling tools like execute_wcps_query (execution) and describe_coverage (coverage description).
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?
Explicit recommendation to check this before executing queries provides clear guidance on when to use, though it doesn't elaborate on when not to use or alternatives beyond siblings.
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.
v0.1.0describe_coverageexecute_wcps_querylist_coveragesvalidate_wcps_querywcps_query_crash_courseScored across 5 tools
Each tool has a clearly distinct purpose: listing coverages, describing a coverage, validating queries, executing queries, and a crash course. There is no overlap in functionality.
Most tools follow a verb_noun pattern with snake_case (e.g., describe_coverage, list_coverages). The exception is 'wcps_query_crash_course', which is a noun phrase, but it remains consistent in using underscores.
With 5 tools, the server covers the essential operations for a datacube query service: exploration, validation, execution, and learning. The count is well-scoped for its purpose.
The tool set covers the key workflows for WCPS querying: list, describe, validate, and execute. Minor gaps exist, such as missing tools for managing coverages or retrieving example queries, but the core functionality is complete.
Ask questions in plain language, get answers from your business database. No SQL required.
GibsonAI MCP server: manage your databases with natural language
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Ask business questions in plain English. Get instant answers from your database, no SQL needed.
