get_account
Permission:account:readOrganization, plan and subscription status, image and LLM credits, next refill time, image models with their cost, ratios, and the carousel cost.
No input. The organization comes from the sign-in.
SMEPost MCP
Create on-brand images and carousels from your AI client
Connect Codex, Claude Code, or any MCP client that supports Streamable HTTP and OAuth. Check credits, generate images and 4-page Instagram carousels, then keep editing the results in SMEPost.
Quick start
Add one URL to your client, then sign in with SMEPost when the client asks.
MCP endpoint
https://smepost.io/api/mcp/content
Codex
Codex opens your browser to sign in and choose an organization.
codex mcp add smepost --url https://smepost.io/api/mcp/content
codex mcp login smepostClaude Code
Add the server, then authenticate from the /mcp menu inside Claude Code.
claude mcp add --transport http smepost https://smepost.io/api/mcp/content
# Then run /mcp inside Claude Code and choose smepost → AuthenticateOther MCP clients
Use the Streamable HTTP transport with this URL. The client discovers sign-in automatically; no API key, plugin, or widget is required.
{
"mcpServers": {
"smepost": {
"type": "http",
"url": "https://smepost.io/api/mcp/content"
}
}
}Test with MCP Inspector
Open Inspector, choose Streamable HTTP, paste the endpoint, then run initialize, tools/list, and tools/call before wiring up your own client.
npx @modelcontextprotocol/inspectorSign-in and permissions
Access uses OAuth 2.1 with PKCE (S256). Your client never sees your SMEPost password.
- The client calls the endpoint and receives 401 with a link to the resource metadata.
- It reads the authorization server metadata and registers itself (dynamic client registration).
- Your browser opens SMEPost. Sign in with a verified account.
- Choose one organization and the permissions to allow. Generations use that organization’s image credits.
- SMEPost redirects back with a one-time code, which the client exchanges for tokens.
- Every call is checked against the token’s organization, your current membership, and the permission it needs.
Permissions
| Permission | Meaning |
|---|---|
account:read | Read plan, subscription status, credit balances, refill date, and costs (get_account). |
images:generate | Start image and carousel generations that spend image credits (generate_image, generate_ig_carousel). |
images:read | Read job progress and results, and get download links (get_generation). |
Tokens
Access tokens last 60 minutes. Refresh tokens last up to 90 days and rotate on every use; reusing an old refresh token revokes the whole connection.
Disconnect
Revoke from your client (it calls the revoke endpoint), or remove your organization membership. New calls fail immediately; a job that is still running stops before it saves and its credits are refunded.
https://smepost.io/.well-known/oauth-protected-resource/api/mcp/content
https://smepost.io/.well-known/oauth-authorization-server/api/content/oauth
https://smepost.io/api/content/oauth/authorize
https://smepost.io/api/content/oauth/token
https://smepost.io/api/content/oauth/register
https://smepost.io/api/content/oauth/revokeTools
Four tools, validated on the server with the same schema shown here. Unknown fields are rejected.
generate_image
Permission:images:generateQueues one on-brand image. The organization’s brand profile and knowledge are applied automatically. Returns a jobId right away.
| Field | Type | Required | Meaning |
|---|---|---|---|
prompt | string | Yes | What the image should show. |
ratio | 1:1 | 4:5 | 9:16 | Yes | Aspect ratio. |
language | en | zh-hk | zh-tw | zh-cn | Yes | Language for any text in the image. |
modelId | gemini-3.1-flash-image-preview | gemini-nano-banana-2.1 | gpt-image-2.5-flare | No | Image model from get_account. Uses the default model when omitted. |
background | opaque | transparent | auto | No | auto (default), opaque, or transparent where the model supports it. |
requestId | string | Yes | Your idempotency key. Reuse it only to retry the identical request. |
maxCredits | number | Yes | Hard ceiling in image credits. A job that costs more is rejected and nothing is charged. |
generate_ig_carousel
Permission:images:generateQueues a 4-page Instagram carousel: one designed collage, split 2×2 into pages, each page upscaled. Results return only when all four upscaled pages are ready, in page order.
| Field | Type | Required | Meaning |
|---|---|---|---|
brief | string | Yes | Topic and key points for the carousel. Links inside the brief are not fetched. |
ratio | 1:1 | 4:5 | Yes | Aspect ratio. |
language | en | zh-hk | zh-tw | zh-cn | Yes | Language for any text in the image. |
requestId | string | Yes | Your idempotency key. Reuse it only to retry the identical request. |
maxCredits | number | Yes | Hard ceiling in image credits. A job that costs more is rejected and nothing is charged. |
get_generation
Permission:images:readStatus, stage, page progress, credit settlement, errors, and — once succeeded — short-lived download links plus a link to keep editing in SMEPost.
| Field | Type | Required | Meaning |
|---|---|---|---|
jobId | string | Yes | The jobId returned when you started the job. |
Examples
Arguments go in tools/call. Structured results are also returned as text for clients that only read text.
{
"method": "tools/call",
"params": {
"name": "generate_image",
"arguments": {
"prompt": "A calm flat-lay of a pour-over coffee set for an autumn menu launch",
"ratio": "4:5",
"language": "en",
"requestId": "autumn-menu-image-001",
"maxCredits": 1
}
}
}{
"method": "tools/call",
"params": {
"name": "generate_ig_carousel",
"arguments": {
"brief": "Four practical tips for brewing better coffee at home, ending with a visit-us call to action",
"ratio": "4:5",
"language": "zh-hk",
"requestId": "brew-tips-carousel-001",
"maxCredits": 3
}
}
}{
"jobId": "cmj_3f9a1c2b7d4e5f60718293a4b5c6d7e8f9012345",
"kind": "ig_carousel",
"status": "queued",
"reservedCredits": 3,
"replayed": false,
"pollAfterMs": 5000
}{
"jobId": "cmj_3f9a1c2b7d4e5f60718293a4b5c6d7e8f9012345",
"kind": "ig_carousel",
"status": "running",
"stage": "upscaling",
"progress": {
"completedPages": 2,
"totalPages": 4
},
"attempts": 1,
"billing": {
"state": "reserved",
"reservedCredits": 3,
"chargedCredits": 0,
"refundedCredits": 0
},
"images": [],
"downloadExpiresAt": null,
"smepostUrl": null,
"error": null,
"pollAfterMs": 8000,
"createdAt": "2026-10-23T08:00:00.000Z",
"completedAt": null
}{
"jobId": "cmj_3f9a1c2b7d4e5f60718293a4b5c6d7e8f9012345",
"kind": "ig_carousel",
"status": "succeeded",
"stage": "completed",
"progress": {
"completedPages": 4,
"totalPages": 4
},
"attempts": 1,
"billing": {
"state": "charged",
"reservedCredits": 3,
"chargedCredits": 3,
"refundedCredits": 0
},
"images": [
{
"page": 1,
"width": 1728,
"height": 2160,
"mimeType": "image/png",
"downloadUrl": "https://smepost.io/api/content/downloads/DOWNLOAD_TOKEN_PAGE_1"
},
{
"page": 2,
"width": 1728,
"height": 2160,
"mimeType": "image/png",
"downloadUrl": "https://smepost.io/api/content/downloads/DOWNLOAD_TOKEN_PAGE_2"
},
{
"page": 3,
"width": 1728,
"height": 2160,
"mimeType": "image/png",
"downloadUrl": "https://smepost.io/api/content/downloads/DOWNLOAD_TOKEN_PAGE_3"
},
{
"page": 4,
"width": 1728,
"height": 2160,
"mimeType": "image/png",
"downloadUrl": "https://smepost.io/api/content/downloads/DOWNLOAD_TOKEN_PAGE_4"
}
],
"downloadExpiresAt": "2026-10-23T08:19:30.000Z",
"smepostUrl": "https://smepost.io/org/ORG_ID/projects/PROJECT_ID/chats/CHAT_ID",
"error": null,
"pollAfterMs": null,
"createdAt": "2026-10-23T08:00:00.000Z",
"completedAt": "2026-10-23T08:04:30.000Z"
}{
"jobId": "cmj_3f9a1c2b7d4e5f60718293a4b5c6d7e8f9012345",
"kind": "ig_carousel",
"status": "failed",
"stage": "failed",
"progress": {
"completedPages": 3,
"totalPages": 4
},
"attempts": 3,
"billing": {
"state": "refunded",
"reservedCredits": 3,
"chargedCredits": 0,
"refundedCredits": 3
},
"images": [],
"downloadExpiresAt": null,
"smepostUrl": null,
"error": {
"code": "GENERATION_TIMEOUT",
"retryable": false
},
"pollAfterMs": null,
"createdAt": "2026-10-23T08:00:00.000Z",
"completedAt": "2026-10-23T08:12:00.000Z"
}{
"error": {
"code": "COST_EXCEEDS_MAX_CREDITS",
"message": "This job costs 3 image credits, above maxCredits 2.",
"retryable": false,
"cost": 3,
"maxCredits": 2
}
}{
"organization": {
"id": "ORG_ID",
"name": "Example Coffee"
},
"plan": {
"planId": "plus",
"effectivePlanId": "plus",
"subscriptionStatus": "active",
"billingPastDue": false
},
"credits": {
"image": {
"remaining": 42.5,
"unlimited": false
},
"llm": {
"remaining": null,
"unlimited": true
},
"nextRefillAt": "2026-11-01T00:00:00.000Z"
},
"imageModels": [
{
"modelId": "gemini-3.1-flash-image-preview",
"label": "Nano Banana 2",
"creditCost": 0.5,
"default": false
},
{
"modelId": "gemini-nano-banana-2.1",
"label": "Nano Banana 2.1",
"creditCost": 1,
"default": true
},
{
"modelId": "gpt-image-2.5-flare",
"label": "GPT Image 2.5 Flare",
"creditCost": 1,
"default": false
}
],
"generation": {
"imageRatios": [
"1:1",
"4:5",
"9:16"
],
"carousel": {
"ratios": [
"1:1",
"4:5"
],
"pageCount": 4,
"creditCost": 3,
"generationModelId": "gpt-image-2.5-flare",
"generationCreditCost": 1,
"upscaleModelId": "gemini-3.1-flash-image-preview",
"upscaleCreditCost": 2
},
"languages": [
"en",
"zh-hk",
"zh-tw",
"zh-cn"
]
},
"scopes": [
"account:read",
"images:generate",
"images:read"
]
}Jobs, retries, and downloads
Generation runs in the background, so a dropped connection never cancels or double-charges a job.
Call get_generation and wait pollAfterMs between calls (about 5s while queued, 8s while running). Stop when status is succeeded or failed.
requestId
The same requestId with the same input returns the original job (replayed: true) and never charges again. The same requestId with different input returns IDEMPOTENCY_CONFLICT. Keys are separate for each client, user, and organization.
maxCredits
Credits are reserved when the job is created, in the same step that checks your balance, so parallel requests can never overspend. A job above maxCredits is refused before anything is reserved.
Automatic retries and refunds
Provider errors and timeouts are retried with backoff, up to 3 attempts, reusing finished work such as the collage and already-upscaled pages. If the job still fails, the reserved credits are refunded once. If your credits were refilled or your plan changed since the job started, the refund is skipped because the balance was already reset.
Download links
Images are stored privately. Each get_generation call returns new links valid for 15 minutes. When a link expires, call get_generation again.
Saved in SMEPost
Every result is saved as an image chat in an “AI app creations” project in your organization, so you can review, edit, and publish it on the website. smepostUrl opens it.
Costs
Prices come from the same model catalog SMEPost uses everywhere. get_account always returns the current values.
| Model | Image credits |
|---|---|
Nano Banana 2 gemini-3.1-flash-image-preview | 0.5 |
Nano Banana 2.1 gemini-nano-banana-2.1Default | 1 |
GPT Image 2.5 Flare gpt-image-2.5-flare | 1 |
| 4-page carousel | 3 |
1 for the collage + 2 for upscaling 4 pages = 3 image credits.
Without enough credits the call returns INSUFFICIENT_IMAGE_CREDITS. SMEPost never switches you to another model or plan.
Errors and limits
Tool failures come back as MCP tool errors with a code and a retryable flag.
| Code | Meaning | Retry? |
|---|---|---|
INVALID_INPUT | The arguments do not match the tool schema. | No |
COST_EXCEEDS_MAX_CREDITS | The job costs more than maxCredits. Raise maxCredits or choose a cheaper model. | No |
INSUFFICIENT_IMAGE_CREDITS | The organization does not have enough image credits. | No |
BILLING_PAST_DUE | A payment is overdue. Update billing in SMEPost. | No |
IDEMPOTENCY_CONFLICT | This requestId was used with different input. Use a new requestId. | No |
TOO_MANY_ACTIVE_JOBS | Too many generations are running for this organization. Wait for one to finish. | Yes |
RATE_LIMITED | Too many requests. Wait a minute. | Yes |
JOB_NOT_FOUND | No job with this jobId exists for this user and organization. | No |
ORGANIZATION_NOT_FOUND | The organization is no longer available. | No |
ACCESS_REVOKED | The connection or organization access was removed. Reconnect the client. | No |
GENERATION_FAILED | The image provider failed. Retried automatically first. | Yes |
GENERATION_TIMEOUT | The image provider took too long. Retried automatically first. | Yes |
VERSION_LIMIT_REACHED | The free plan’s version limit was reached. | No |
TEMPORARILY_UNAVAILABLE | SMEPost could not complete the call. Retry shortly. | Yes |
HTTP responses
- 401 — missing, expired, or revoked token. The WWW-Authenticate header points to the resource metadata; sign in again or refresh.
- 403 insufficient_scope — the token lacks the permission the tool needs. Reconnect and allow it. Also returned for browser requests from another website.
- 413 — the request body is larger than 64 KB.
- 429 — rate limited. Respect Retry-After.
Limits
- Up to 120 MCP requests per minute for each user and organization.
- Up to 10 new generation requests per minute.
- Up to 4 queued or running jobs per organization.
- Prompts up to 4000 characters; carousel briefs up to 1200 characters.
Troubleshooting
- The client keeps asking me to sign in.
- Your refresh token expired or was revoked. Reconnect (Codex: codex mcp login smepost; Claude Code: /mcp → Authenticate).
- tools/call returns 403 insufficient_scope.
- You unticked a permission when connecting. Reconnect and allow it.
- The job is queued for a long time.
- Jobs start immediately and are recovered every minute if a start is missed. A retry waits for its backoff first. Keep polling get_generation.
- A download link returns 404.
- Links expire after a few minutes. Call get_generation again for new links.
- I see IDEMPOTENCY_CONFLICT.
- Use a new requestId for a new request. Reuse one only to retry exactly the same arguments.
- Where do I see the result in SMEPost?
- Open smepostUrl, or find the “AI app creations” project in your organization.
Client status
Any client with Streamable HTTP and OAuth uses the same endpoint. This table shows which clients have been checked end to end.
| Client | Status |
|---|---|
| Codex | Setup documented, live check pending |
| Claude Code | Setup documented, live check pending |
| MCP Inspector | Setup documented, live check pending |
| Other Streamable HTTP + OAuth clients | Setup documented, live check pending |