@baselyai/conector

The agent you already use (Claude Code, Codex, Cursor, VS Code Copilot, Kimi Code, Windsurf, Gemini CLI) talking to your Basely setup: sites, database, storage, domains, servers and publishing.

One package, two faces:

• basely, the terminal command: login, sites, servers, publish, status, call.
• basely mcp, an MCP server on stdio that exposes the same operations as tools. Every one of those editors speaks MCP, so it is one implementation and three lines of configuration per tool.

Both call the same Basely HTTP API. The connector has no business logic; it is a client. Every rule (scope, rate limit, who owns what) stays on the platform.

Install and log in

npx -y @baselyai/conector login

The terminal prints a short code and opens the Basely Hub at /hub/conectores/aprovar?code=.... You give the connector a name and a scope, and the token comes back to the terminal by exchanging the code (never through the URL). It is stored in ~/.config/basely/token with mode 0600.

BASELY_TOKEN in the environment overrides the file (CI). BASELY_URL overrides the platform URL.

Set up your editor

Claude Code (.mcp.json in the project, or ~/.claude.json):

{ "mcpServers": { "basely": { "command": "npx", "args": ["-y", "@baselyai/conector", "mcp"] } } }

VS Code / Copilot (.vscode/mcp.json):

{ "servers": { "basely": { "type": "stdio", "command": "npx", "args": ["-y", "@baselyai/conector", "mcp"] } } }

Cursor (.cursor/mcp.json): same mcpServers object as Claude Code.

Codex (~/.codex/config.toml):

[mcp_servers.basely]
command = "npx"
args = ["-y", "@baselyai/conector", "mcp"]

Tools

| tool | does | scope | |---|---|---| | basely_whoami | account, plan, credits and this token's scope | account | | basely_profile | my professional profile: how it stands, what is missing to publish, showcase sites | account | | basely_profile_update | write my professional profile and, with publicar: true, put it live at /p/{slug} | account | | basely_account | my account details: name, e-mail, language, company, phone, country, timezone | account | | basely_account_update | change name, language, company, phone, country and timezone. Not the e-mail | account | | basely_list_sites | your sites and your clients' sites, with engine and state | account | | basely_list_servers | your servers and the ones you operate | account | | basely_list_clients | clients linked to you, with their sites and servers | account | | basely_site_create | create a site in your account and get its id and {slug}.baselyai.com address | account | | basely_site_upload | send the site folder (zip, up to 100 MB, images included) and go live if your plan allows | site | | basely_site_resources | schema, default table, data REST, storage of a site | site | | basely_provision_database | create tables in site_{id} | site | | basely_query | read-only SQL (one SELECT) in the site's role, 200 rows | site | | basely_upload_asset | upload a file to the site's storage | site | | basely_publish | publish: HTML/PHP to Basely, Web App to a server | site + server | | basely_deploy_status | state of the last deployment | site | | basely_list_domains | the account domains: status, SSL, expiry, which site they point to | domain | | basely_domain_search | check up to 20 names: free or not, 1st year and renewal price (same as the Hub) and the Hub link to buy. Never buys | domain | | basely_point_domain | point an account domain to a server | domain | | basely_server_logs | last jobs and events of a server | server | | basely_server_command | closed verbs: backup-agora, reiniciar-agente, atualizar-agente | server |

Business tools added in 0.7.0 (read only)

| tool | does | scope | |---|---|---| | basely_workflows | the business's automations: enabled, published, what changed since | business | | basely_workflow | one automation: the draft graph, the live version, people per step | business | | basely_workflow_runs | runs of one automation, each with its steps and results | business | | basely_bdesk_pipelines | every pipeline of the business with its stages | business | | basely_funnel_orders | orders from the funnels (refunds stay in the Hub) | business | | basely_funnel_responses | survey answers from the funnels | business | | basely_bseller_orders | store orders: product, amount, status, dates, buyer name and email (refunds stay in the Hub) | store |

Drafts added in 0.7.0 (write inside the business, level 2)

| tool | does | scope | |---|---|---| | basely_workflow_create | create an automation as a draft, switched off (from a template or a graph) | business | | basely_workflow_save | save the draft of an automation; the live version does not change | business | | basely_email_design_create | create a block email (from a template or a document) | business | | basely_email_design_save | save a block email's name and document | business | | basely_blog_post_create | create a blog post as a draft, written by your agent | business | | basely_bdesk_pipeline_save | replace the stages of the main pipeline | business |

Publishing, sending and turning automations on are not here: they are level 3 and go through the owner's approval.

Actions on behalf of the business: the owner approves (0.7.0)

Sending email or messages, publishing a site, funnel, campaign or product, turning an automation or routine on, pointing a domain or running a server command (level 3) do not happen right away. The call answers 202 with a pedidoId and the action waits in the Hub, Approvals, where the owner reads what will go out and approves or declines. Approved, the platform makes exactly that call once; declined or undecided in 72 hours, nothing happens.

• basely_approval <pedidoId> tells the state: esperando, executando, executado (with the action's answer), falhou, recusado or vencido.
• The CLI waits by itself in basely create, basely deploy and basely publish, and prints where to approve.
• Test sends to your own account (basely_marketing_campaign_test, basely_email_template_test) still go right away.
• basely deploy uploads first (that only writes to the site's repository) and then asks to publish.

Run basely help <tool> for the fields of any tool.

Social media

One tool set for the whole social workflow of a client: plan the week, make the art, cut the video, and hand the plan to a person to approve.

| tool | does | scope | |---|---|---| | basely_social_clients | the businesses whose social you run, with channels and pending count | client | | basely_social_pending | posts waiting for approval (100 per page, with total and proximoOffset) | client | | basely_social_calendar | what is scheduled, what went out, what failed | business | | basely_social_submit | submit a plan of posts and get the approval link back | business | | basely_social_batch | what a person decided about a submitted plan | business | | basely_social_batch_cancel | withdraw a whole plan you submitted; published posts stay | business | | basely_social_media | the media library and how much of the plan quota is used | business | | basely_social_media_add | upload an image (base64, up to 8 MB) | business | | basely_social_media_upload_url | signed URL for a large file (video) | business | | basely_social_media_confirm | register the file you just PUT | business | | basely_social_image | generate artwork (fast or premium); if it takes longer than 25 s you get pendente: true and a job to follow with basely_social_job | business | | basely_social_video | generate a short AI video (premium) | business | | basely_social_transcribe | cut a video, step 1: transcribe and propose the clips | business | | basely_social_clip | cut a video, step 2: render the chosen clips in 9:16 | business | | basely_social_job | follow a media job | business | | basely_social_plugs | read the per channel automations | business | | basely_social_groups | read the Facebook groups the seller belongs to that serve this client | business | | basely_social_metrics | what went out and what failed, with content credit usage | client |

Facebook groups are read only, and that is not a limitation of ours. Meta removed the Groups API on 22 April 2024, permissions and all, and there is no replacement. Nobody publishes to a group from a server. The seller does it, in their own logged in session, through the Basely browser extension, one group at a time. You can read the groups and put posts in the queue; the click is theirs. With more than one group, write a different text for each: the same text across groups is what gets a seller banned by the group admins.

Nothing you submit is published by the connector. basely_social_submit puts the posts in the queue and returns an approval link; a person opens it, drops what they do not like and confirms, and only then the platform schedules on the networks. There is no approve tool, on purpose: a post goes out in your client's name, in public, and it does not come back.

Generating art, video and clips spends content credits from the account that pays the tool. The brake is the balance: when it runs out the answer is a 402 with the plan link, never a worse image.

Your own professional profile is the one public thing the connector does put live, and that is on purpose: it is your voice, not a client's.

What is deliberately not a tool: approving or publishing a post, switching on an automation, connecting or disconnecting a social account, buying, cancelling, revealing passwords, changing e-mail, deleting sites or servers. Actions with money, ownership, or a public voice happen in the Hub, with a real session. An agent acting on its own with a leaked token cannot spend or destroy.

The token

• Per seller, named, revocable with one click in the Hub (Connectors).
• Explicit scope: which clients, sites, servers and social businesses. A token for one project does not see the others.
• 90 days, renewed silently while in use, dead after 30 days unused.
• bsly_ + 32 random bytes, stored only by hash, shown once. Not a JWT.
• Rate limit per token: 60 calls per minute, 2 publishes per minute, 10 generations per minute. The whole account also has a ceiling across its tokens (150 calls, 4 publishes, 20 generations per minute): ten tokens do not make ten times the limit.

Out-of-scope calls return 403 and are recorded in the account's history.

What the token can do: levels by area (0.7.0)

Besides which clients, sites and businesses, each token says what it can do in each area (CRM, sites, social media, email marketing, Money and so on):

| Level | Means | |---|---| | 0 | nothing in that area | | 1 | read | | 2 | write inside the business: drafts, edits, moving a deal, tags, notes | | 3 | act on the business's behalf (send, publish, turn an automation on): only through a request the owner approves in the Hub |

A new token starts read only in every area; you open the rest when you create it or approve the terminal login. Level 3 is not offered yet: it arrives with the approval queue. Charging, refunds, prices, purchases and giving access to someone else are never a tool, at any level.

A call above the token's level returns 403 NIVEL_NAO_LIBERADO with the area and the nivel it needs. A tool name that is not in the registry returns 403 FERRAMENTA_DESCONHECIDA. Tokens created before 0.7.0 keep what they could do until they are replaced.

Safe retries

Every write the package sends carries an Idempotency-Key, and the same key on its retries (network error, 5xx, 429). If the first attempt already acted, the server answers with the saved result (Idempotent-Replayed: true) instead of acting twice. Your own HTTP client can do the same: any POST to /api/conector/** accepts the header, for 24 hours.

Every call is recorded

Each call (which token, which tool, the path, the result, when) is in the Hub, Connectors, "Every call", for 90 days. The account owner gets an email when a new connector is created.

CLI

basely whoami
basely sites
basely servers
basely create [--name "My site"] [--web-app] [--server <id> --domain <domain>]   # --server registers an app already running there
basely deploy ./my-site [--site <id>] [--name "My site"]
basely publish <siteId> [--server <id>]
basely status <siteId>
basely call basely_query '{"siteId":"...","sql":"select * from submissions"}'
basely tools
basely logout