PhenoWorks MCP
Connect your AI assistant to PhenoWorks with the Model Context Protocol (MCP). The assistant can find projects and datasets, inspect analysis modules, run pipelines, and retrieve results using your PhenoWorks account permissions.
This package runs the MCP server that your assistant connects to. You need a running PhenoWorks server and an MCP-compatible assistant; installing this package does not install PhenoWorks or provide an AI model.
Before you start
- Use Python 3.11 or newer.
- Have your PhenoWorks server URL, such as
https://your-phenoworks-server. - Create an API key in your PhenoWorks account settings.
Your server URL is the address of your own PhenoWorks installation, not the
public documentation website. Both the server root and a URL ending in /api
are accepted.
Install
Install from PyPI in a Python virtual environment:
pip install phenoworks-mcp
phenoworks-mcp --help
The PhenoWorks Python SDK and MCP runtime are installed automatically. To
upgrade an existing installation, run pip install --upgrade phenoworks-mcp.
If you already use uv, you can run the package without a separate install command:
uvx phenoworks-mcp --help
Connect to Claude Desktop
Follow the Claude Desktop setup tutorial to create a dedicated uv environment, configure your local PhenoWorks connection, and start chatting with Claude.
Connect over local HTTP
For a client that accepts a Streamable HTTP MCP URL, start the server in a terminal. For example, in a macOS or Linux shell:
export PHENOWORKS_API_BASE_URL="https://your-phenoworks-server"
export PHENOWORKS_API_KEY="YOUR_API_KEY"
phenoworks-mcp
Leave the process running and add this MCP server URL to your assistant:
http://127.0.0.1:8787/mcp
There are two different URLs: PHENOWORKS_API_BASE_URL points to PhenoWorks;
http://127.0.0.1:8787/mcp points to this MCP process. The default listens only
on your computer, so a cloud-hosted assistant cannot reach it through its own
localhost.
You can change the local port if needed:
phenoworks-mcp --port 8788
When configured with a fixed API key, callers of this MCP process act as that PhenoWorks account. Keep this mode local to a trusted user.
Try your first requests
Once connected, ask your assistant:
- "Check my PhenoWorks connection and show which account I am using."
- "List my projects, then show the datasets in the project I choose."
- "Find datasets configured for thermal imagery in project 7."
- "Show the available analysis modules and explain the inputs of one I choose."
- "Check the status of pipeline 123 and list its output artifacts."
Replace example IDs with IDs from your server. A useful first sequence is
phenoworks_health, phenoworks_me, then list_projects. A successful health
check establishes connectivity; phenoworks_me checks the account credentials.
For analysis, ask the assistant to discover the installed blocks and validate
the steps before using run_dataset_pipeline. Pipeline execution needs suitable
dataset inputs and a working PhenoWorks worker. Running or cancelling a pipeline
changes server state. Clients that support form elicitation receive a submission
confirmation; clients without it can submit directly, so use your assistant's
tool approval controls as appropriate.
Available tools
| Task | Tools |
|---|---|
| Check connectivity and identity | phenoworks_health, phenoworks_me |
| Explore projects | list_projects, get_project |
| Environmental data | get_dataset_ancillary_data |
| Explore datasets | list_datasets, get_dataset, get_dataset_summary, filter_datasets_by_modality |
| Understand data types | list_data_types |
| Prepare and upload data | get_data_import_guide |
| Inspect analysis modules | search_analysis_blocks, describe_analysis_block, review_analysis_block_code |
| Retrieve module citations | get_analysis_block_citation |
| Prepare and run analysis | validate_pipeline_steps, run_dataset_pipeline |
| Monitor runs | list_pipeline_runs, get_pipeline_run, cancel_pipeline_run |
| Retrieve results | list_artifacts, download_artifact |
Every tool result is sent back to the model on each turn, so large outputs are
kept small: list_pipeline_runs and list_artifacts return one page
(limit/offset, newest first) with a total and next_offset, run summaries
omit logs and payloads, and get_pipeline_run returns only the last log_lines
lines of the logs (200 by default). Instead of listing a run's files,
get_pipeline_run adds an artifacts overview: a count per artifact type and
the run's results table, so an agent can offer that one file when a user asks
for "the results" of a run with thousands of per-plot outputs. list_artifacts
accepts an artifact_type filter for fetching one kind of file.
Available data and actions depend on the account's server permissions. Modality filtering checks the dataset's declared modalities, not whether its files have already been uploaded.
Where downloaded files go
download_artifact saves files on the computer running this MCP server.
That is right when the server runs on your own computer, as with Claude Desktop
or Claude Code over stdio. A shared server started with --no-local-downloads
saves nothing: the tool checks access and returns the artifact ID, filename, and
size without local_path, and the caller's client offers the download. The
PhenoWorks web app runs its MCP service this way and shows a download button in
the agent chat.
By default, the workspace is .phenoworks-agent-workspaces under the process's
working directory. To choose a location, set an absolute path:
export PHENOWORKS_AGENT_WORKSPACE_DIR="/absolute/path/to/phenoworks-downloads"
For a desktop client, add this variable to its MCP configuration's env object.
With an API key or token, the server acts for one user, so files are saved
directly in the workspace as artifact_<id>_<filename>. With
--forward-auth-headers, the server is shared, so each file goes under
user_<id>/<session>/ inside the workspace. The user folder comes from the
authenticated identity, and the session folder comes from the
x-phenoworks-agent-session header (default when it is missing). An assistant
running on another computer will need shared storage or another way to retrieve
those local files.
Other authentication options
Use exactly one credential mode:
| Mode | Configuration |
|---|---|
| API key | PHENOWORKS_API_KEY |
| Bearer token | PHENOWORKS_AUTH_TOKEN instead of the API key |
| Each caller supplies credentials | --forward-auth-headers over HTTP |
For forwarded authentication, unset fixed credentials before starting:
unset PHENOWORKS_API_KEY PHENOWORKS_AUTH_TOKEN
phenoworks-mcp \
--api-base-url https://your-phenoworks-server \
--forward-auth-headers
Each MCP caller must send either X-API-Key or Authorization: Bearer ....
This mode is not available with stdio. Remote deployments also need a reachable
address, HTTPS, and appropriate access controls; changing --host alone does
not configure those services.
Troubleshooting
| What you see | What to check |
|---|---|
phenoworks-mcp: command not found |
Activate the environment where you installed it, or give your client the executable's full path. |
| Missing API endpoint | Set PHENOWORKS_API_BASE_URL or pass --api-base-url. The MCP CLI uses this variable, not the SDK's PHENOWORKS_API_URL. |
| Missing or conflicting credentials | Set exactly one authentication mode. Remove an old bearer token when switching to an API key. |
| Connection refused | Check that PhenoWorks is running and that the MCP host can reach its URL. For HTTP clients, also keep the MCP process running. |
| HTTP 401 or 403 | Check the key/token, its expiry where applicable, and the account's access permissions. |
| Tools do not appear after a change | Restart the MCP connection or client to refresh tool discovery. |
| Downloads are not on your laptop | Check the MCP host's workspace directory; files are saved where the server runs. A server started with --no-local-downloads saves none. |
Cannot create the download folder |
Set PHENOWORKS_AGENT_WORKSPACE_DIR to an absolute folder the MCP process can write to (no placeholders such as YOUR_USERNAME), then restart the server. |
See the PhenoWorks documentation for setting up projects, data, and workflows.
Implementation and lifecycle
The Python SDK owns the pooled asynchronous HTTP client, credential validation,
and API error decoding. Inside phenoworks_mcp:
| Module | Responsibility |
|---|---|
cli.py |
Resolves arguments and environment configuration, then starts the server. |
server.py |
Builds the server, owns the client lifespan, and registers each tool group. |
tools/ |
One module per tool group: catalog, blocks, pipelines, artifacts. |
api.py |
PhenoWorksGateway: per-request credentials, API errors as tool errors, per-caller workspace folders on shared servers. |
responses.py |
Pure functions that shape API records into compact results (summaries, pages, log tails). |
blocks.py |
Block API paths, read-only source excerpts, and pipeline step resolution. |
workspace.py |
Safe download locations inside the agent workspace. |
settings.py |
Every limit, default, and environment setting. |
instructions.py |
Server instructions describing the data model and analysis workflow. |
Numeric tool parameters declare their bounds in the tool schema, so clients see them and out-of-range values are rejected before a tool runs. Source docstrings describe parameters, return contracts, validation, and resource ownership.
build_server(client) transfers client cleanup to the MCP server lifespan.
Embedders invoking tools directly outside that lifespan must close the client
themselves. Forwarded credentials are supplied per request and never written into
shared client defaults. The backend remains the authority for access checks.
get_dataset_summary first fetches the dataset, then concurrently fetches its
surveys, all file pages, ancillary data, layers, pipeline runs, and artifacts. It returns
the keys dataset, surveys, contents, ancillary_data, layers,
pipeline_runs, and artifacts, and fails if a required request fails.
contents summarizes, for the dataset and for each survey, the data products
present with their sensors (modalities), named bands, processing methods, and
plot coverage, so an agent can match analysis blocks to the data.
run_dataset_pipeline accepts optional modalities and data_products filters
that narrow which files reach the blocks. The server also publishes agent
instructions describing this vocabulary and the analysis planning workflow. This reduces sequential network
waits; it is not a measured production latency guarantee.
Explicit pipeline step versions are preserved; otherwise the account's preferred
version is resolved from the catalog. Canonical names take
precedence over class/display aliases, and argument values must be objects.
validate_pipeline_steps checks compatibility without submitting work. Pipeline
submission returns a single run_id, which is also the run's operation id.
Clients without form elicitation retain headless submission behavior. Once a
client advertises support, a failed confirmation stops submission; it never
silently authorizes the run.
Downloads stream in 1 MiB chunks to unique temporary files and atomically replace
the final artifact path. The last successful download wins for the same artifact
path; no caller consumes another download's partial file. Temporary files are
removed on normal errors and cancellation. A download that cannot create its
folder or write its file fails with a tool error naming the path. With
forwarded credentials, paths are scoped by the API-authenticated user and a
sanitized x-phenoworks-agent-session grouping header. That header is not an
authorization credential. SHA-256 and byte counts describe
the downloaded bytes. The workspace is local to the MCP host, so remote agent
hosts need shared storage or a separate retrieval mechanism.
Offline checks
The server uses MCP 2.x (mcp.server.mcpserver). From the repository root,
install the local package and run these standard-library tests without pytest:
pip install -e ./packages/phenoworks-mcp
python -m unittest discover -s packages/phenoworks-mcp/tests -v
Tests cover concurrent summaries, canonical catalog resolution, invalid step arguments, concurrent downloads, and confirmation failures. They use fake API clients and temporary directories; they do not submit real pipelines.
Describe and explain analysis blocks
Use search_analysis_blocks to find the canonical block name, then:
describe_analysis_block(name, version=None)returns its description, schema, manifest, class name, authors, tags, and installed version. This is catalog metadata, not an inferred explanation of the implementation.review_analysis_block_code(name, version=None, start_line=1, max_lines=200)returns version-matched metadata and the storedblock.pysource, with line numbers and a full-source SHA-256 digest. The agent can explain processing steps, inputs, outputs, and side effects using this evidence. No code is imported or executed, and the tool does not generate an automated correctness verdict.
For example, after finding image_2_hsv, call:
{"name": "image_2_hsv", "start_line": 1, "max_lines": 200}
Continue with next_start_line and the returned version to inspect subsequent
pages; next_start_line: null means the end has been reached. max_lines accepts
1–1000 lines. Imported helper files are not included, so explanations should
identify those limits rather than assume their behavior.
Both tools forward the caller's credentials and respect the backend's detail
and source visibility rules. If PHENOWORKS_AGENT_MCP_ALLOWED_TOOLS is
configured, include both new names in that allowlist. Restart the MCP server and
start a new agent conversation to refresh cached tool discovery.
Shared SDK transport
MCP uses phenoworks_sdk.AsyncPhenoWorksClient for API requests, credentials,
errors, and streamed downloads. The SDK is a package dependency; there is no
separate MCP HTTP client. Local development resolves the sibling
../phenoworks-sdk package, and the MCP Docker image includes it.
MCP retains tool definitions, pipeline confirmation/version resolution, request-header extraction, workspace confinement, and progress reporting. Forwarded credentials are passed per request, never stored on the shared HTTP transport. API-key and bearer-token modes remain available.
The filter_datasets_by_modality tool accepts modality, optional project_id,
and optional study_id. It calls the SDK's datasets.filter_by_modality helper,
which filters the visible datasets' declared supported_modalities. It does not
claim that a dataset already contains files of that modality.
Discover and install modules through the agent
The agent searches search_analysis_blocks(scope="installed") first and uses
the account's preferred versions when preparing pipeline steps. If no suitable
module is installed, it can search scope="all", including modality and
data_product filters, and inspect candidates with
describe_analysis_block(name, version, scope="all").
After showing the matches and the user choosing a module,
install_analysis_block(name, version) displays a confirmation for that exact
version. Accepting adds it to the caller's library; declining or dismissing leaves
the library unchanged. A client without elicitation support must install through
the Modules UI. Installation does not upload or replace a shared package.
Once installed, the agent can validate a pipeline using that version. Running the pipeline has its own separate confirmation. Start a new agent chat after updating the MCP server if an existing chat still has the previous tool definitions.
Dataset files
list_dataset_files returns a bounded page with modality, data-product, path,
and exact metadata filters. get_dataset_file reads one record.
Plot and survey identifiers are optional labels in metadata_json; filenames
and folders do not determine those labels. get_dataset_summary reads every
file page and reports file counts and metadata-based survey/plot coverage.
list_data_types includes each product's administrator-controlled indexable flag.
get_data_import_guide explains the three upload options and the metadata ZIP
layout (one JSON sidecar per plot listing its files), with a worked example and
the modalities and data products the server accepts, so agents can tell users
how to organize their data before importing it.
Environmental data
get_dataset_ancillary_data(dataset_id, collection_date=None) reads persisted ancillary records through the caller-authenticated dataset API. It reports dated rainfall in millimeters and inches, temperature, humidity, wind, UTC coverage, and provider provenance. Missing values remain null; zero rainfall is an actual zero. For absent records, including an unmatched date, the tool returns found: false with No ancillary data found for this dataset.
Dataset creation automatically queues environmental data retrieval when both coordinates or a location name are provided. The UI supplies the selected collection date (default today, UTC). API callers may provide ancillary_date; without it the job explicitly records creation_date as its date basis. fetch_ancillary_data: false opts out. Name-only locations must resolve unambiguously. Recent model estimates and partial-day totals must not be described as complete measured rainfall. The tool preserves old snow-inclusive precipitation separately from rainfall.
Metadata
Release files for phenoworks-mcp 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| phenoworks_mcp-0.4.0.tar.gz | 50.7 kB | With provenance | Details for phenoworks_mcp-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| phenoworks_mcp-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for phenoworks_mcp-0.4.0-py3-none-any.whl |
Total release size: 97.2 kB
Release files / phenoworks_mcp-0.4.0.tar.gz
| Download URL | phenoworks_mcp-0.4.0.tar.gz |
|---|---|
| Size | 50.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4324f27f9de2f947af920d254aec7f745d9a05c497463b433b9b50f40cf13b5
|
|
BLAKE2b-256 checksum How to use checksums |
3a0cd1d2e7c8be4052182b4c31d07c2df85dc3de60370ab573b47b07ce515139
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logRelease files / phenoworks_mcp-0.4.0-py3-none-any.whl
| Download URL | phenoworks_mcp-0.4.0-py3-none-any.whl |
|---|---|
| Size | 46.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9448398879224d158a46c9be51d086c5bbb148e532038ca1680fbd8b311fe984
|
|
BLAKE2b-256 checksum How to use checksums |
2917074acb6adf0cd3518083cfaacde0366fefae98285f5c07377b59333d6960
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logSecurity for phenoworks-mcp 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for phenoworks_mcp-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.