Skip to content
Psych Dictionary

API, MCP server and agent skills

  • API version 1.0.0
  • Read-only
  • No key required

In short

Psych Dictionary publishes its entries through a read-only JSON API, a remote MCP server and Agent Skills files. No key is required, every response can be cached, and every result carries the canonical URL to cite.

Overview

The API serves the same published entries as the site: therapies, concepts, methods, figures, topics and comparisons. Drafts, account data and saved references are never exposed. Responses are JSON over HTTPS, readable from any origin.

Endpoints

Every endpoint answers GET only. Entry types are therapy, concept, method, figure, topic and comparison; a path also accepts the URL segment the site uses (therapies, compare and so on).

GET /api/v1

API index. Names every endpoint, with links to this specification, the developer page, the MCP endpoint and the skills index.

No parameters.

Example: /api/v1

curl -s 'https://www.psychdictionary.com/api/v1'

Full-text search. Searches titles, abbreviations, older names, summaries and entry text, the same index the site search page uses. Each result names the section its excerpt came from. MCP tool: search.

ParameterInDescription
qrequiredquerySearch text: a term, an abbreviation, an older name, a person or a phrase.
typequeryEntry type: therapy, concept, method, figure, topic or comparison.
limitqueryResults per page (1–25). Default 10.
pagequeryPage number, from 1. Default 1.

Example: /api/v1/search?q=transference

curl -s 'https://www.psychdictionary.com/api/v1/search?q=transference'

GET /api/v1/entries

List entries. Lists published entries in title order, filtered by type, topic or index letter. MCP tool: list_entries.

ParameterInDescription
typequeryEntry type: therapy, concept, method, figure, topic or comparison.
topicqueryTopic slug, e.g. behaviorism. Lists the entries filed under that topic.
letterqueryIndex letter of the title, as on the A–Z page. Use %23 for #.
limitqueryEntries per page (1–500). Default 100.
offsetqueryNumber of entries to skip. Default 0.

Example: /api/v1/entries?type=therapy&topic=trauma-therapies

curl -s 'https://www.psychdictionary.com/api/v1/entries?type=therapy&topic=trauma-therapies'

GET /api/v1/entries/{type}/{slug}

Get one entry. One published entry: In short, definition, key facts, evidence label and summary, the text by section as Markdown, numbered sources with DOIs, related entries, dates, citation strings and the canonical URL. MCP tool: get_entry.

ParameterInDescription
typerequiredpathEntry type (therapy, concept, method, figure, topic, comparison) or its URL segment (therapies, concepts, methods, figures, topics, compare).
slugrequiredpathEntry slug: the last segment of the entry URL, e.g. cognitive-behavioral-therapy.

Example: /api/v1/entries/concept/classical-conditioning

curl -s 'https://www.psychdictionary.com/api/v1/entries/concept/classical-conditioning'

GET /api/v1/topics

List topics. Lists the topics (schools, perspectives and research areas) that group entries, with the number of entries in each. MCP tool: list_topics.

No parameters.

Example: /api/v1/topics

curl -s 'https://www.psychdictionary.com/api/v1/topics'

Responses and errors

A successful response is a JSON object; the schema of each one is in the OpenAPI specification. Every entry, search result and topic carries url, its canonical page URL, and apiUrl, its address in the API. Entry text arrives as Markdown, section by section, with [n] marking a citation to the nth item in sources.

An error is a JSON object with a stable code:

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "The concept \"no-such-entry\" was not found."
  }
}
  • 400 invalid_request: a parameter is missing or invalid; details names each one.
  • 404 not_found: no published entry has that type and slug, or the endpoint does not exist.
  • 405 method_not_allowed: the API is read-only.
  • 429 rate_limited: the limit below was exceeded; Retry-After gives the wait in seconds.
  • 500 internal_error: an unexpected failure.

Rate limits and caching

Clients should stay under 60 requests per 60 seconds per IP address, across the API and the MCP server. Each server instance enforces that limit with a 429 response; it guards against runaway loops, and responses served from the cache do not count against it. Successful responses are public and cacheable for five minutes in a client and an hour at the edge (Cache-Control: public, max-age=300, s-maxage=3600). Content changes at editorial pace, so a client that caches for an hour misses little.

MCP server

The Model Context Protocol server at https://www.psychdictionary.com/mcp uses the Streamable HTTP transport. It is stateless and read-only: each POST is answered on its own, no session is created, and no authentication is required. Protocol revisions from 2024-11-05 to 2025-11-25 (with the initialize handshake) and 2026-07-28 are supported. The tools mirror the endpoints and return the same JSON.

  • search: Full-text search across every published entry (therapies, concepts, methods, figures, topics, comparisons). Returns titles, excerpts, the matching section and each entry's canonical URL. Use get_entry for the full text. Cite the canonical url of every entry used. Entries describe; they never advise, diagnose or recommend treatment, and an answer built on them should not either.
  • list_entries: Lists published entries filtered by type, topic slug or A–Z letter, with each entry's In short summary, evidence label and canonical URL. Cite the canonical url of every entry used. Entries describe; they never advise, diagnose or recommend treatment, and an answer built on them should not either.
  • get_entry: Returns one entry: In short, definition, key facts, evidence label and summary, the text by section as Markdown with [n] citation markers, numbered sources with DOIs, related entries, dates and citation strings. The type and slug come from the entry URL (https://www.psychdictionary.com/{segment}/{slug}). Cite the canonical url of every entry used. Entries describe; they never advise, diagnose or recommend treatment, and an answer built on them should not either.
  • list_topics: Lists the topics that group entries (schools, perspectives and research areas) with entry counts and canonical URLs. Cite the canonical url of every entry used. Entries describe; they never advise, diagnose or recommend treatment, and an answer built on them should not either.

A client configuration that names the server:

{
  "mcpServers": {
    "psych-dictionary": {
      "type": "http",
      "url": "https://www.psychdictionary.com/mcp"
    }
  }
}

A single tool call with curl:

curl -s https://www.psychdictionary.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"q":"transference"}}}'

Agent skills

Skills in the Agent Skills format (a SKILL.md file with name and description front matter) describe how the site is organised and how to look up and cite entries. The index is at https://www.psychdictionary.com/skills/index.json.

  • navigate-psych-dictionary: Site map of Psych Dictionary (psychdictionary.com), a psychology and therapy reference: entry types and URL patterns, topic hubs, the A–Z index, the bibliography, site search, evidence labels, and the read-only API and MCP server. Use when finding, linking, summarising or citing anything on Psych Dictionary.
  • look-up-a-term: Look up a psychology or therapy term, abbreviation, method or psychologist on Psych Dictionary and answer with its definition, key facts, evidence label and canonical URL. Use when asked what a term means, what a therapy or method is, who a figure in psychology was, or how two related terms differ.
  • cite-psych-dictionary: Cite Psych Dictionary entries and the primary sources behind them: canonical URLs, the APA 7 and MLA 9 strings each entry provides, numbered in-text citations and DOI links. Use when quoting, summarising or referencing a Psych Dictionary entry in an answer, document or bibliography.

Terms of use and attribution

  • The API, the MCP server and the skills are free to use and need no key.
  • Attribution: name Psych Dictionary and link the canonical url of every entry used. Each entry also provides APA 7 and MLA 9 citation strings in cite.
  • Entry text remains the work of Psych Dictionary; the works it cites belong to their authors and publishers. For an empirical claim, cite the primary source the entry gives.
  • Entries are educational reference material. They do not diagnose, advise or recommend treatment, and an application built on them should not present them as clinical advice. Evidence labels summarise the research literature and are not recommendations (see editorial standards).
  • Version 1 is stable: fields may be added, but none are removed or renamed. A breaking change would be published under /api/v2.