Midgard Science

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 Code
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
Check the connection and list the tools
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.

Example arguments
{}

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 certifications give 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 total counts every match.
  • per_page integerListings per page, 1 to 100. Default 50.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.

Example arguments
{}

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.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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_...).
Example arguments
{
  "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_...).
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.
Example arguments
{
  "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.