---
title: "Developers: MCP server, APIs and agent access | KONDEVS"
description: "How AI agents and integrations use kondevs.com: the MCP server, markdown pages, feeds, the partner Content API, JSON errors, rate limits and versioning."
canonical: "https://www.kondevs.com/developers/"
language: "en"
type: "website"
image: "https://www.kondevs.com/images/og-default.png"
---

# Developers

> For the complete index of this site, see [llms.txt](https://www.kondevs.com/llms.txt); the whole site in one file: [llms-full.txt](https://www.kondevs.com/llms-full.txt).

Machine-readable access to KONDEVS: the MCP server, markdown pages, feeds and the Content API, with errors, limits and versioning documented.

KONDEVS is an integration, BPM and AI consultancy. This site is built to be read and used by AI agents as well as people: everything below is live, and most of it needs no key.

## Quickstart: no key needed

List the tools of the MCP server, then search the articles:

```
curl -s https://www.kondevs.com/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

curl -s https://www.kondevs.com/mcp -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_articles","arguments":{"query":"webMethods","limit":3}}}'
```

Read any page as markdown, or list the HTTP endpoints:

```
curl -s https://www.kondevs.com/services/eai-integration/ -H "Accept: text/markdown"

curl -s https://www.kondevs.com/services/eai-integration.md

curl -s https://www.kondevs.com/api/
```

## Public interfaces

| Interface | Address | Access | What it gives you |
| --- | --- | --- | --- |
| MCP server | `POST /mcp`, card [server-card.json](https://www.kondevs.com/.well-known/mcp/server-card.json) | none | JSON-RPC 2.0 over Streamable HTTP. Tools: `search_articles`, `get_article`, `list_services`, `get_company_info`. Listed in the official MCP Registry as [com.kondevs/content-hub](https://registry.modelcontextprotocol.io/v0.1/servers/com.kondevs%2Fcontent-hub/versions/latest). |
| A2A agent | `POST /api/a2a`, card [agent-card.json](https://www.kondevs.com/.well-known/agent-card.json) | none | `message/send`: questions about KONDEVS and the Content Hub. |
| Markdown | any page, or its address with `.md` (`/about.md`) | none | Send `Accept: text/markdown`, or ask for the `.md` address: YAML frontmatter and the page content, no site chrome. An unknown address answers 404 in markdown too. |
| Feeds | [feed.xml](https://www.kondevs.com/content-hub/feed.xml) (RSS), [feed.json](https://www.kondevs.com/content-hub/feed.json) (JSON Feed) | none | The newest 50 articles in full: key takeaways, body, FAQ, sources. |
| Site guides | [llms.txt](https://www.kondevs.com/llms.txt), [llms-full.txt](https://www.kondevs.com/llms-full.txt), [sitemap.xml](https://www.kondevs.com/sitemap.xml) | none | What the site holds, when to use it, every page. |
| API descriptions | [openapi.json](https://www.kondevs.com/openapi.json), [api-catalog](https://www.kondevs.com/.well-known/api-catalog), [/api/](https://www.kondevs.com/api/) | none | OpenAPI 3.1, the RFC 9727 catalog and a JSON index of every endpoint. |
| Discovery | [ai-catalog.json](https://www.kondevs.com/.well-known/ai-catalog.json), [agent skills](https://www.kondevs.com/.well-known/agent-skills/index.json) | none | The ARD catalog and the agent skills index. |
| Health | `GET /api/health` | none | Liveness probe. |

## Content API for publishing partners

The Content API publishes, updates and removes Content Hub articles. It serves content partners such as the VISIBILIO platform; it is not an open, self-service API.

- **API keys.** On the live site there is no self-service sign-up (the sandbox below issues its own test keys). KONDEVS issues keys to vetted partners: write to [info@kondevs.com](mailto:info@kondevs.com) with your organisation, the integration purpose, the expected volume and the scope you need (`content:read` or `content:write`). `GET /api/oauth/register` returns the same instructions as JSON.
- **Authentication.** `Authorization: Bearer <key>`, or exchange the key for a one-hour token with OAuth 2.0 `client_credentials` at `POST /api/oauth/token` (ES256, keys at [jwks.json](https://www.kondevs.com/.well-known/jwks.json)). The full guide is [auth.md](https://www.kondevs.com/auth.md).
- **Endpoints.** `GET /api/content/catalog`, `GET /api/content/tags`, `POST /api/content/`, `PUT /api/content/{slug}`, `DELETE /api/content/{slug}`, `POST /api/content/images` (one image, multipart), and the public `GET /api/content/version` and `GET /api/content/{slug}` (a published article; a draft with the key). Covers are optional; a create answers the article's `url` relative to the site. Schemas and examples are in [openapi.json](https://www.kondevs.com/openapi.json).
- **SDK and CLI.** [@kondevs/content](https://www.npmjs.com/package/@kondevs/content) on npm wraps every operation of [openapi.json](https://www.kondevs.com/openapi.json) (Node 18 or newer, no dependencies): `npx @kondevs/content get what-is-eai`, `publish article.json --dry-run`, and `--sandbox` with `KONDEVS_SANDBOX_URL=https://kondevs-sandbox.pages.dev`. The key comes from `KONDEVS_API_KEY`.
- **Sandbox.** [kondevs-sandbox.pages.dev](https://kondevs-sandbox.pages.dev) runs the same API on its own store, never on kondevs.com, with test data that may be deleted at any time. `POST /api/oauth/register` there answers a write key at once, valid 7 days (5 per hour per address); its pages are noindex. The key is a direct Bearer key (`Authorization: Bearer <key>`), not an OAuth client credential: `/api/oauth/token` does not exchange it. Point a client at it with `servers[1]` of [openapi.json](https://www.kondevs.com/openapi.json).
- **Testing without side effects.** On the live API, `POST /api/content/?dry_run=1` (or `"dry_run": true` in the body) runs authentication, limits and the full validation and stores nothing, so it is the safe way to test a payload. The answer says what would be created: `slug`, `url`, `status_after`; a slug that is taken answers 409, as a real POST would.
- **Content advice.** A successful create, update or dry run may carry `warnings`: the AEO body contract (a relative date, a superlative with no source in its sentence, no answer in the first 60 words, a section that opens with a back-reference, no buyer question at all). Advice only: the article is stored all the same, and a clean body carries none.
- **Safe retries.** Send an `Idempotency-Key` header with `POST /api/content/`: a retry with the same key and body gets the first answer again (marked `Idempotent-Replayed: true`) for 24 hours; the same key with a different body answers 422. `PUT` and `DELETE` are idempotent by definition.

```
curl -s -X POST "https://www.kondevs.com/api/content/?dry_run=1" \
  -H "Authorization: Bearer $KONDEVS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c0b8e-2d4a-4f7e-9a51-3c2e8d7b1a90" \
  -d @article.json
```

## All endpoints

The same list as `GET /api/` and the paths of [openapi.json](https://www.kondevs.com/openapi.json): all three are built from one table.

| Endpoint | Access | What it does |
| --- | --- | --- |
| `GET /api/` | none | This index: every endpoint with its method, access and purpose, and where the docs are. |
| `GET /api/health` | none | Liveness probe. |
| `POST /mcp` | none | MCP server (JSON-RPC 2.0, Streamable HTTP): search and read articles, list services, company facts. |
| `POST /api/a2a` | none | A2A agent (JSON-RPC 2.0, message/send). |
| `GET /api/content/version` | none | Content API version and the rendering capabilities of this site. |
| `GET /api/content/catalog` | token (content:read) | Published articles, categories and tags, 100 articles a page unless ?limit= says otherwise (at most 500); next_cursor and a Link rel="next" header name the same next page. |
| `POST /api/content/catalog` | token (content:write) | Rebuild the article lists and counts from the stored articles after parallel writes: a dry run answering each change (changes[]) and the catalog it leaves; ?apply=1 writes them. |
| `POST /api/content/` | token (content:write) | Publish an article; covers are optional; dry_run validates without storing (a taken slug answers 409); accepts Idempotency-Key. |
| `GET /api/content/{slug}` | none | One article: 200 when it is published, 404 when there is none; a draft answers 200 only with a content key. |
| `PUT /api/content/{slug}` | token (content:write) | Update an article: each field the payload sends replaces the stored one, a field it leaves out keeps its value (the FAQ, key takeaways and sources too; an empty list clears one). |
| `DELETE /api/content/{slug}` | token (content:write) | Unpublish an article. |
| `GET /api/content/tags` | token (content:read) | The tags of the published articles: the same list as the catalog's. |
| `POST /api/content/images` | token (content:write) | Upload one image for an article (multipart/form-data: file, slug, variant; at most 10 MB); the answer names its URL. dry_run checks without storing. |
| `POST /api/oauth/token` | client | OAuth 2.0 client_credentials: exchange an issued secret for a 1-hour bearer token (RFC 6749 errors). |
| `GET /api/oauth/register` | none | How to obtain credentials (issued by human review, no self-service; the sandbox issues its own test keys). |
| `POST /api/oauth/register` | none | Production: answers like GET, registration is manual, no client is created and no credential is issued. On the sandbox server (kondevs-sandbox.pages.dev) a key is issued: 201, a test write key valid 7 days. |
| `POST /api/contact` | none | The contact form of /contacts/ (CSRF token, honeypot, consent, rate limit; Turnstile only when configured); answers { success, message }. While outbound mail is not configured it answers success: false and names info@kondevs.com. |

## Errors

Every `/api/*` error is JSON with a stable `code`, what went wrong (`error` on a Content API answer, `message` on the authentication and limit answers), a `hint` and, as `docs`, the code's own entry below. A validation failure lists every field at once in `errors` (and `details`, the same list), each `{ field, message }`.

```
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "status": "error",
  "code": "not_found",
  "message": "No API endpoint at /api/nope.",
  "hint": "Check the path. GET /api/ lists the endpoints; /openapi.json describes them.",
  "docs": "https://www.kondevs.com/developers/#error-not_found"
}
```

`bad_request` HTTP 400

The request is malformed. Check the request against the OpenAPI description at /openapi.json.

`validation_failed` HTTP 400

The payload failed validation; errors[] names each field. Fix the fields listed in `errors`; the payload schema is in /openapi.json. Add ?dry_run=1 to validate without storing.

`unsupported_version` HTTP 400

The X-Content-API-Version header asks for a major version this server does not serve. Send X-Content-API-Version: 1, or leave the header out.

`invalid_idempotency_key` HTTP 400

The Idempotency-Key header is not 1-255 visible ASCII characters. Send a unique value per request, for example a UUID.

`unauthorized` HTTP 401

No valid Bearer key or token. Send Authorization: Bearer <token>. Keys are issued to publishing partners; see /auth.md.

`forbidden` HTTP 403

The key or token is valid but does not carry the scope this call needs. Writes need content:write, the catalog content:read (write includes read); see /auth.md.

`not_found` HTTP 404

No endpoint or no article at this address. Check the path. GET /api/ lists the endpoints; /openapi.json describes them.

`method_not_allowed` HTTP 405

This path does not accept this method. Use one of the methods in the Allow header.

`conflict` HTTP 409

An article with this slug already exists. Update it with PUT /api/content/{slug}, or publish under another slug.

`idempotency_in_progress` HTTP 409

A request with this Idempotency-Key is still running. Retry in a few seconds (Retry-After).

`payload_too_large` HTTP 413

The body is larger than the limit. Send a smaller body: an article payload may be at most 30 MB, images included.

`unsupported_media_type` HTTP 415

The body is not JSON. Send Content-Type: application/json.

`idempotency_key_reused` HTTP 422

This Idempotency-Key was already used with a different body. Use a new Idempotency-Key for a different request.

`rate_limited` HTTP 429

Too many requests from this address. Wait for the number of seconds in the Retry-After header, then retry.

`internal_error` HTTP 500

The server failed. Retry the same request later. A write cut short may be half done: a create answers its retry with 409 and lists the stored article then; GET /api/content/catalog lists what is published. If it persists, write to info@kondevs.com.

`bad_gateway` HTTP 502

An upstream service failed. Retry later. If it persists, write to info@kondevs.com.

`unavailable` HTTP 503

The service is not available. Retry later. If it persists, write to info@kondevs.com.

Two protocols keep their own format: the OAuth endpoints answer as RFC 6749 defines (`error`, `error_description`), and `/mcp` and `/api/a2a` answer JSON-RPC 2.0 errors.

## Rate limits

| Endpoint | Limit | Counted |
| --- | --- | --- |
| `POST /mcp` | 120 per minute | per IP |
| `POST /api/a2a` | 60 per minute | per IP |
| `GET /api/content/catalog` | 60 per minute | per IP |
| `POST /api/content/catalog` | 10 per hour | per IP |
| `GET /api/content/tags` | 60 per minute | per IP |
| `POST /api/content/` | 30 per hour | per IP |
| `PUT /api/content/{slug}` | 30 per hour | per IP |
| `DELETE /api/content/{slug}` | 30 per hour | per IP |
| `POST /api/content/images` | 120 per hour | per IP |
| `POST /api/oauth/token` | 30 per minute | per IP |
| `POST /api/oauth/register` | 30 per minute | per IP |
| `POST /api/contact` | 5 per 10 minutes | per IP |

Rate-limited responses carry `RateLimit-Policy` and `RateLimit` (the IETF RateLimit header fields: quota, window, remaining, seconds to reset) and `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (Unix time). A 429 adds `Retry-After` in seconds.

## Versioning and deprecation policy

The Content API is at version 1.1.0: every Content API response carries `X-Content-API-Version`, and `GET /api/content/version` returns it with the rendering capabilities of this site. Changes within major version 1 only add fields. A client can pin the major version with `X-Content-API-Version: 1` (also `1.1`, `v1`); a request for another major version is refused with 400 `unsupported_version` before anything runs. A breaking change gets a new major version. Anything that is going to be removed will be announced on this page and with `Deprecation` and `Sunset` response headers for at least 90 days before it goes. Nothing is deprecated today.

## Questions

Write to [info@kondevs.com](mailto:info@kondevs.com). For what KONDEVS does and when to call on it, read [llms.txt](https://www.kondevs.com/llms.txt).