--- title: "Shipshape Data agent guide" description: "How AI agents can read, use and contact Shipshape Data: markdown twins, section indexes, the AI readiness assessment, and contact conventions." canonical: https://shipshapedata.com/agents.md language: en-GB --- # Shipshape Data: agent guide > How AI agents can read, use and contact Shipshape Data, a London AI consultancy that builds the data foundation first. This file is the agent-facing front door; the human one is https://shipshapedata.com/. ## Who this site belongs to Shipshape Data is a London AI consultancy. We build the data foundation your AI depends on (cloud data warehouse, medallion architecture, semantic layer), the connective layer that lets models reach governed data safely (including MCP), and the AI on top: strategy, development, and delivery that stays past go-live. Proof lives in the case studies: AI document processing that freed 1.5 days of admin a week at Smarter Services, automated customer engagement at 1NCE, and a multilingual AI assistant for Slimstock. ## What an agent can do here today - **Call the API.** A keyless, read-only REST API at `https://shipshapedata.com/api/v1` (it self-describes): services, industries, case studies, search across 169 guides, and the AI readiness assessment with server-side scoring. OpenAPI 3.1 spec at [/openapi.json](https://shipshapedata.com/openapi.json); quickstart at [/developers/](https://shipshapedata.com/developers/); auth story (none needed) at [/auth.md](https://shipshapedata.com/auth.md). - **Connect over MCP.** Two Streamable HTTP servers, no auth: `https://shipshapedata.com/mcp` (product: list_services, get_case_studies, search_resources, get_ai_readiness_questions, score_ai_readiness, get_contact_info) and `https://shipshapedata.com/mcp/docs` (docs: search_docs, get_page for any page's full markdown, list_sections). Server cards: [product](https://shipshapedata.com/.well-known/mcp/server-card.json), [docs](https://shipshapedata.com/.well-known/mcp/docs-server-card.json). Both are in the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=com.shipshapedata) as `com.shipshapedata/shipshape-data` and `com.shipshapedata/shipshape-data-docs`. - **Ask over NLWeb or A2A.** `POST https://shipshapedata.com/ask` with `{"query": "..."}` returns NLWeb-schema results from the site's content (SSE streaming with `streaming=true`). The A2A agent card is at [/.well-known/agent-card.json](https://shipshapedata.com/.well-known/agent-card.json); `message/send` to `https://shipshapedata.com/a2a` gets a direct answer with source links. - **Read everything as markdown.** Every content page has a twin at its URL plus `index.md` (for example `https://shipshapedata.com/case-studies/1nce/index.md`). Append `?mode=agent` to any page URL to get the same twin. Pages advertise twins with a `rel="alternate" type="text/markdown"` link tag. - **Navigate from the indexes.** Start at [llms.txt](https://shipshapedata.com/llms.txt) (site guide, under 8k characters), then the section indexes: [services](https://shipshapedata.com/services/llms.txt), [industries](https://shipshapedata.com/industries/llms.txt), [case studies](https://shipshapedata.com/case-studies/llms.txt), [resources](https://shipshapedata.com/resources/llms.txt) (169 annotated guides). - **Assess AI readiness.** Fetch the 16 questions (`GET /api/v1/ai-readiness/questions` or the MCP tool), ask the user each one, then score the answers (`POST /api/v1/ai-readiness/score`): same maths as the [interactive version](https://shipshapedata.com/ai-readiness/), returning a 0-100 score, maturity band, and per-area advice. Stateless; nothing is stored. - **Use the in-page tools.** On the homepage, WebMCP tools are registered via `document.modelContext` (`contact_shipshape_data` prepares the enquiry form for the user to review and send; `get_shipshape_overview` summarises the company), and the contact form carries `toolname`/`tooldescription` attributes. - **Install the skills and configs.** The official toolkit at [github.com/shipshapedata/agent-tools](https://github.com/shipshapedata/agent-tools) carries agent skills (`npx skills add shipshapedata/agent-tools`, listed on [skills.sh](https://skills.sh/shipshapedata/agent-tools)), MCP configs for Claude Code and Cursor, and a Claude Code plugin manifest. - **Use the SDKs.** `shipshape-data` on [npm](https://www.npmjs.com/package/shipshape-data) (`npx shipshape-data readiness`) and [PyPI](https://pypi.org/project/shipshape-data/) (`pip install shipshape-data`): zero-dependency SDKs and CLIs covering the whole surface, assessment included. - **Make contact on a user's behalf.** Email [hello@shipshapedata.com](mailto:hello@shipshapedata.com) with what the user is working with, what they want AI to do, and what is driving the timing. A person replies, usually within one working day, and we say honestly if we are not the right fit. The website's Talk to us form reaches the same team. There are deliberately no programmatic write endpoints. ## Discovery files - [ard.json](https://shipshapedata.com/.well-known/ard.json): agent readiness descriptor listing our agent-facing surfaces. - [openapi.json](https://shipshapedata.com/openapi.json): OpenAPI 3.1 spec for the read API. - [MCP server card](https://shipshapedata.com/.well-known/mcp/server-card.json) and manifest at `/.well-known/mcp`. - [api-catalog](https://shipshapedata.com/.well-known/api-catalog): RFC 9727 linkset of the API surface. - [schemamap.xml](https://shipshapedata.com/schemamap.xml): NLWeb schema feed of key pages and their schema.org types. - [sitemap.xml](https://shipshapedata.com/sitemap.xml): every page with lastmod. - [robots.txt](https://shipshapedata.com/robots.txt): open to AI crawlers and user-triggered agents, with content signals declared. ## Conventions - Markdown twins are served as `text/markdown` and carry `X-Robots-Tag: noindex` so they never compete with their canonical HTML page in search. Cite the canonical HTML URL, read the markdown. - No authentication is needed anywhere: API, MCP, and pages are all public and read-only ([auth.md](https://shipshapedata.com/auth.md)). - Everything is stateless and side-effect free, so the whole surface doubles as a sandbox: call anything, as often as is reasonable. - Errors from the API are always JSON with a `code`, `message`, and docs link. - British English throughout.