MCP
MCP server and tools
https://midgardscience.aramous.com/api/mcp, over Streamable HTTP. Searching needs no sign-in. To order, the agent calls sign_inwith the person's email, asks them for the six-digit code from the email, then calls verify_code. Or connect with an API key in the Authorization header.
claude mcp add --transport http midgard-science https://midgardscience.aramous.com/api/mcp claude mcp add --transport http midgard-industrial https://midgardindustrial.aramous.com/api/mcp
npx @modelcontextprotocol/inspector --cli https://midgardscience.aramous.com/api/mcp --transport http --method tools/list
Cursor, VS Code and other clients: configuration. Each tool carries the MCP annotations readOnlyHint, destructiveHint, idempotentHint and openWorldHint. A tool error is a result with isError and the text {"error": {"code", "message"}}.
list_categories
List categories
- No sign-in
- Read-only
Lists each site ("science", "industrial"), its service categories and the spec fields a request in each category takes. Each field says whether it is required (a value to place the request), needed (a value or spec_unknown before confirm_labs), recommended, when it applies, and whether it goes on the acceptance checklist. Call it before create_request to get a valid site, category and spec keys. No sign-in needed.
{}Returns the same object as GET /api/v1/categories, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 500server_errorSomething failed on the server; try again.
search_suppliers
Search the directory
- No sign-in
- Read-only
Keyword search of the public supplier directory, the same search as the website. Returns a page of listings with location, categories, certificates and services as each listing states them. Use it to browse or to apply exact filters: category, state or province, certificate, purchase orders. For work described in plain language and ranked by fit, use find_suppliers. No sign-in needed.
Arguments
- q stringWords to search for.
- site stringThe site: "science" or "industrial". Defaults to the site this address serves.
- category stringA category slug from list_categories.
- region stringA state or province code as listings give it, e.g. CA or OH.
- cert stringOnly listings that name this certificate or standard, as the tags in
certificationsgive it, e.g. ISO 9001, AS9100 or ITAR. ITAR also matches a listing that states it is registered with the US State Department (itar_registered). - accepts_po booleanOnly suppliers that take purchase orders.
- page integerThe page to return, from 1. Default 1. The answer's
totalcounts every match. - per_page integerListings per page, 1 to 100. Default 50.
{
"category": "assays",
"q": "kinase",
"per_page": 5
}Returns the same object as GET /api/v1/suppliers, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 400invalid_requestUnknown site, or a category of another site.
- 500server_errorSomething failed on the server; try again.
find_suppliers
Find suppliers for a request
- No sign-in
- Read-only
The first call for "find a lab, CRO, shop or supplier for this work". Describe the work in plain language; returns up to 10 suppliers ranked by fit (fit: "strong" when the listing states the work and every standard and place the query requires; "possible" when it states part of it, or when the search fell back to keywords), each with the reasons taken from its profile, and a request_draft to pass to create_request once the person has checked it. missing lists details still needed: ask the person about each. One with not_known_allowed true may go in spec_unknown when they don't know it. Takes up to a minute. No sign-in needed: 10 searches an hour per network address, 100 an hour when signed in.
Arguments
- query string, requiredThe work, in the person's words: what, how many, any standards and deadlines.
- site stringThe site: "science" or "industrial". Defaults to the site this address serves.
- category stringA category slug from list_categories.
- region "any" | "na" | "us" | "eu" | "india" | "asia"Region key: any, na, us, eu, india, asia. "eu" includes the UK. For a US state or a city, name it in the query, or use search_suppliers with region set to the state code.
- standard stringOnly suppliers whose listing names this standard, e.g. GLP or ISO 13485.
- limit integerHow many suppliers, 1 to 10. Default 8.
{
"query": "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis",
"limit": 3
}Returns the same object as POST /api/v1/search, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 400invalid_requestUnknown site, category or region.
- 429rate_limitedOver the hourly search limit. The message says when to try again.
- 500server_errorSomething failed on the server; try again.
get_supplier
Get a supplier
- No sign-in
- Read-only
One listing by slug (from find_suppliers or search_suppliers): profile, services and listed prices, standards as the listing names them (the supplier confirms them in its quote), public records, shared contact mailboxes, and ways to continue: contact the supplier directly, or ask for a quote through a request. No sign-in needed.
Arguments
- slug string, requiredThe supplier's slug, from a search.
{
"slug": "example-lab"
}Returns the same object as GET /api/v1/suppliers/{slug}, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 404not_foundNo listed supplier with that slug.
- 500server_errorSomething failed on the server; try again.
sign_in
Sign in: send a code
- No sign-in
- Adds, does not overwrite
- Not safe to repeat
- Reaches outside the server
Step 1 of signing in, needed only to order or read orders. Emails a six-digit code to the person's own address: ask them for it and never guess it. Then ask them for the code and call verify_code. Orders are placed for, and visible to, this address. Each call sends another email; the two newest codes work. Not needed when the connection sends an API key.
Arguments
- email string, requiredThe person's email address.
{
"email": "you@company.com"
}Returns the same object as POST /api/v1/auth/code, as JSON text.
readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true
Errors
- 400no_sessionThe client keeps no Mcp-Session-Id, so it cannot hold a sign-in; connect with an API key instead.
- 400invalid_requestNot an email address.
- 429rate_limitedToo many codes from this network, or for this address.
- 500server_errorSomething failed on the server; try again.
verify_code
Sign in: check the code
- No sign-in
- Adds, does not overwrite
- Not safe to repeat
- Stays on the server
Step 2 of signing in: checks the six-digit code the person read from the email sent by sign_in, and signs this connection in as that email. The code works once, for 10 minutes, with 5 tries.
Arguments
- email string, requiredThe same email as in sign_in.
- code string or integer, requiredThe six-digit code the person read from the email.
{
"email": "you@company.com",
"code": "123456"
}Returns {"signed_in": true, "email", "message"} as JSON text; the session is signed in and no key is returned.
readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint false
Errors
- 400no_sessionThe client keeps no Mcp-Session-Id.
- 400invalid_codeThe code is wrong.
- 400code_expiredExpired or used; call sign_in again.
- 429too_many_triesToo many wrong codes for this address.
- 500server_errorSomething failed on the server; try again.
whoami
Who is signed in
- Needs sign-in
- Read-only
The email this connection acts for, and the key in use. Use it to check the sign-in before ordering.
{}Returns the same object as GET /api/v1/me, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 500server_errorSomething failed on the server; try again.
upload_file
Upload a file
- Needs sign-in
- Adds, does not overwrite
- Not safe to repeat
- Reaches outside the server
Stores a drawing, CAD file, sequence file, sample sheet or protocol for a request, the same as POST /api/v1/uploads. Send the file as content_base64 with its filename, or as url, an https address the server can download it from without signing in. Up to 50 MB; content_base64 suits files up to 3 MB, larger files go by url. The filename's extension decides whether the type is accepted. Returns the file's url: put it in the category's spec field of type file (list_categories), in create_request or with request_action set_spec. The file joins the first request that names it; for another request, upload it again. Downloads by url: 30 an hour.
Arguments
- filename stringThe file's name with its extension, e.g. bracket.step or plasmid.gb. Needed with content_base64; with url, the name the address or its download gives is used when this is left out.
- content_base64 stringThe file's bytes, base64-encoded (a data: URL works too), for files up to 3 MB. Send this or url, not both.
- url stringAn https address the file downloads from without signing in, up to 50 MB. Send this or content_base64, not both.
{
"url": "https://files.example.com/drawing-rev-c.pdf"
}Returns the same object as POST /api/v1/uploads, as JSON text.
readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 400invalid_requestNeither or both of content_base64 and url, no filename with content_base64, base64 that does not decode, or a url that is not https on a public host.
- 400invalid_fileEmpty, larger than 50 MB, or a type that is not accepted.
- 400fetch_failedThe url did not answer with the file within 30 seconds.
- 429rate_limitedMore than 30 downloads by url this hour.
- 500server_errorSomething failed on the server; try again.
create_request
Create a request
- Needs sign-in
- Adds, does not overwrite
- Not safe to repeat
- Reaches outside the server
Places a request for quotes as the signed-in email, on a site and category from list_categories. A request_draft from find_suppliers is a good start; check the details with the person first. The request starts as new with suggested suppliers, and nothing goes to any supplier until request_action confirm_labs. suppliers only pre-selects slugs (an unknown slug is refused); they are asked when you run confirm_labs. Returns the request and a status_url the person can open. Send idempotency_key, a value unique to this request, so a retry with the same arguments returns the same request; reusing it with any other arguments is refused. To attach a drawing or other file, store it with upload_file and put the returned url in the category's field of type file (list_categories). The response's missing lists needed fields still open; confirm_labs refuses until each has a value or is in spec_unknown.
Arguments
- site string, requiredThe site: "science" or "industrial".
- category string, requiredA category slug from list_categories.
- title string, requiredA short title for the work.
- spec objectThe category's spec fields, key to value (see list_categories). A select field takes one of its options; a file field takes a url from upload_file.
- spec_unknown array of stringSpec keys the person does not know. Needed fields must have a value or be listed here before confirm_labs.
- quantity integerHow many, as a whole number counted in the category's unit (list_categories gives
unit: samples, parts, ...). - details stringAnything else the suppliers should know.
- needed_by stringA date (2027-01-15) or the buyer's words (mid January).
- budget stringShown to the suppliers asked.
- supplier stringOne preferred supplier slug.
- suppliers array of stringSupplier slugs to pre-select. Nobody is asked until confirm_labs.
- contact_name stringThe person's name, shown to the suppliers asked.
- organization stringThe person's company or institution, shown to the suppliers asked.
- country stringThe country the work is for or ships to.
- idempotency_key stringA value unique to this request, e.g. a UUID. Send the same value with the same arguments on a retry to get the request already created instead of a second one; the same value with any argument changed is refused with idempotency_conflict.
{
"site": "science",
"category": "assays",
"title": "IC50 for 40 compounds in a kinase assay",
"spec": {
"assay": "IC50 against a 10-kinase panel",
"sample_type": "small molecules in DMSO",
"replicates": "Triplicate",
"controls": "vehicle and staurosporine on every plate"
},
"quantity": 40,
"needed_by": "2027-01-15",
"idempotency_key": "3f6c2a1e-8d4b-4e57-9a0c-5b7e2d1f9c84"
}Returns the same object as POST /api/v1/requests, as JSON text.
readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 400invalid_requestUnknown site or category, a missing required field, a select value that is not one of its options, or a placeholder value. The message names the field.
- 409idempotency_conflictThe idempotency_key was already used with different arguments; send a new one.
- 500server_errorSomething failed on the server; try again.
list_requests
List requests
- Needs sign-in
- Read-only
The signed-in email's requests, newest first, including orders placed on the website. Filter by status to find the ones waiting on the person (quoted, delivered). late is true when a step is past its date.
Arguments
- status stringOne status or several, comma-separated: new, sourcing, quoted, accepted, paid, in_progress, delivered, closed, cancelled, introduced.
- site stringOnly this site's requests: "science" or "industrial". Left out, every site's.
- limit integerDefault 20.
- starting_after stringTo page: the last id of the previous page.
{
"status": "quoted,delivered",
"limit": 20
}Returns the same object as GET /api/v1/requests, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 400invalid_requestUnknown status or site, or a starting_after id that is not yours.
- 500server_errorSomething failed on the server; try again.
get_request
Get a request
- Needs sign-in
- Read-only
One request: status, suggested suppliers (supplier_id for confirm_labs), the date suppliers are asked to reply by (reply_by), each asked supplier's status, quotes (each with its id for accept_quote and its ways to continue), milestones (each with its state and who it waits on), payments, shipments, files and the public timeline. After a supplier declines or misses reply_by, next_suppliers lists who to invite with invite_more. missing lists needed fields still open. Check it again later to see when status becomes quoted.
Arguments
- request_id string, requiredThe request id (req_...).
{
"request_id": "req_Xq3v9KpL2aB7"
}Returns the same object as GET /api/v1/requests/{id}, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo request with that id for this account.
- 500server_errorSomething failed on the server; try again.
get_messages
Read messages
- Needs sign-in
- Read-only
The message thread on a request, oldest first: what the person sent ("you") and the updates and supplier questions passed on to them ("midgard").
Arguments
- request_id string, requiredThe request id (req_...).
{
"request_id": "req_Xq3v9KpL2aB7"
}Returns the same object as GET /api/v1/requests/{id}/messages, as JSON text.
readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo request with that id for this account.
- 500server_errorSomething failed on the server; try again.
send_message
Send a message
- Needs sign-in
- Adds, does not overwrite
- Not safe to repeat
- Reaches outside the server
Adds a message to a request's thread: an answer to a supplier's question, or more detail. It is passed on. Each call adds another message.
Arguments
- request_id string, requiredThe request id (req_...).
- message string, requiredThe text to pass on, up to 4000 characters.
{
"request_id": "req_Xq3v9KpL2aB7",
"message": "Samples ship on Monday."
}Returns the same object as POST /api/v1/requests/{id}/messages, as JSON text.
readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo request with that id for this account.
- 500server_errorSomething failed on the server; try again.
accept_quote
Accept a quote
- Needs sign-in
- Cannot be undone
- Not safe to repeat
- Reaches outside the server
Accepts a quote the way the person chose; it cannot be undone, so confirm with them first. continue "midgard" keeps the order on the site under the order terms: terms_name must be the full name the person typed to accept the terms; ask them for it and never fill it in yourself. The answer may carry payment_url, a Stripe Checkout link for the person to open and pay; you cannot pay. continue "own" takes the quote to the supplier directly; the supplier's contact details then appear on the timeline.
Arguments
- quote_id string, requiredThe quote id (qt_...), from get_request.
- continue "midgard" | "own", requiredHow the person continues.
- terms_name stringFor "midgard": the name the person typed to accept the order terms.
- po stringA purchase order number. With one, payments are invoiced.
- billing_email stringWhere invoices go, if not the signed-in email.
- revision stringParts: the file revision the order is built to, e.g. Rev C.
- outcome_reason "price" | "lead_time" | "capability" | "other"Optional. The main reason, shared with the suppliers not chosen: price, lead_time, capability or other. Ask the person; never choose it yourself.
{
"quote_id": "qt_Hn4sD8wQ1zR6",
"continue": "midgard",
"terms_name": "<the name the person typed>"
}Returns the same object as POST /api/v1/quotes/{id}/accept, as JSON text.
readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo quote with that id.
- 400invalid_requestNo terms_name for "midgard", an unknown outcome_reason, or the quote can no longer be accepted.
- 500server_errorSomething failed on the server; try again.
request_action
Act on a request
- Needs sign-in
- Cannot be undone
- Not safe to repeat
- Reaches outside the server
The order page's other actions; confirm each with the person first. confirm_labs (status new): send the request to suppliers by supplier_ids (from suggestions) or slugs, with an optional reply_by date. invite_more (status sourcing or quoted): send to more suppliers by supplier_ids from next_suppliers. set_spec (status new): fill spec fields or mark them spec_unknown. set_milestone_date: move the date of a step that waits on the person (stage, date). set_acceptance (status new): what the order must meet; fixed once the requests have gone out. answer_question: answer a supplier's question (rfq_id, answer). add_shipment: record what is being sent (material, samples). pay: returns payment_url, a Stripe Checkout link for the person to open; you cannot pay. decide_change: approve or decline a change (change_id, approve). accept_results or request_rerun (reason) once delivered. request_release: storage, give notice to leave. To accept a quote use accept_quote.
Arguments
- request_id string, requiredThe request id (req_...).
- action "confirm_labs" | "invite_more" | "set_spec" | "set_milestone_date" | "set_acceptance" | "answer_question" | "add_shipment" | "pay" | "decide_change" | "accept_results" | "request_rerun" | "request_release", requiredWhich action. The other arguments it reads are named after it in each argument's description.
- supplier_ids array of stringconfirm_labs: ids from the request's suggestions. invite_more: 1 to 3 ids from next_suppliers.
- reply_by stringconfirm_labs: YYYY-MM-DD, 2 to 30 days from today, the date suppliers are asked to reply by. Default 5 business days.
- spec objectset_spec: spec fields to fill, key to value.
- spec_unknown array of stringset_spec: spec keys the person does not know.
- stage stringset_milestone_date: the step (stage from get_request milestones) whose waiting_on is buyer.
- date stringset_milestone_date: the new date, YYYY-MM-DD.
- slugs array of stringconfirm_labs: supplier slugs.
- acceptance objectset_acceptance: term to value.
- rfq_id stringanswer_question: the question's rfq id.
- answer stringanswer_question: the answer.
- material objectadd_shipment: what is being sent.
- samples array of objectadd_shipment: the samples in the shipment, each with your id for it, a description and an optional amount.
- booked_by "client" | "lab"add_shipment: who books the courier.
- payment_id stringpay: the payment id (pay_...) from get_request.
- change_id stringdecide_change: the change id (co_...).
- approve booleandecide_change: true to approve.
- reason stringrequest_rerun: what is wrong.
- kind stringrequest_rerun: the kind of problem.
- quantity stringrequest_rerun: how much is affected.
- photos array of stringrequest_rerun: links to files uploaded to this order.
{
"request_id": "req_Xq3v9KpL2aB7",
"action": "confirm_labs",
"supplier_ids": [
"sup_Tb6yE2mC9kW1"
]
}Returns the same object as POST /api/v1/requests/{id}/actions, as JSON text.
readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo request with that id for this account.
- 400invalid_requestThe action does not fit the request's status, a field is missing, confirm_labs while needed fields are open, or set_spec with a key the category does not have or a select value that is not one of its options.
- 500server_errorSomething failed on the server; try again.
cancel_request
Cancel a request
- Needs sign-in
- Cannot be undone
- Safe to repeat
- Reaches outside the server
Cancels a request before it is paid; open quotes are withdrawn and the suppliers asked are told it is closed. It cannot be undone, so confirm with the person first. reason stays internal; outcome_reason is what the suppliers are told.
Arguments
- request_id string, requiredThe request id (req_...).
- reason stringInternal; never sent to suppliers.
- outcome_reason "price" | "lead_time" | "capability" | "other"Optional. The main reason, told to the suppliers asked: price, lead_time, capability or other. Ask the person; never choose it yourself.
{
"request_id": "req_Xq3v9KpL2aB7",
"reason": "Ordered elsewhere",
"outcome_reason": "lead_time"
}Returns the same object as POST /api/v1/requests/{id}/cancel, as JSON text.
readOnlyHint false, destructiveHint true, idempotentHint true, openWorldHint true
Errors
- 401sign_in_requiredNot signed in: call sign_in and verify_code, or connect with an API key.
- 404not_foundNo request with that id for this account.
- 400invalid_requestAn unknown outcome_reason.
- 409not_cancellableAlready paid or under way.
- 500server_errorSomething failed on the server; try again.