문서 / MCP 연결과 도구 참조

MCP 연결과 도구 참조

AI 에이전트에 조립스페이스를 연결하고, 사용할 수 있는 도구와 필요한 입력 항목을 살펴보세요.

MCP 클라이언트 연결

MCP를 연결하면 AI 에이전트가 대화 중에 조립스페이스 프로젝트를 조회하고 필요한 도구를 사용할 수 있습니다. 원격 Streamable HTTP 연결을 지원하므로 클라이언트에 아래 URL을 등록하면 됩니다. 컴퓨터에 조립스페이스 MCP 패키지를 따로 설치할 필요는 없습니다.

에이전트가 터미널에서 명령을 설치하고 실행할 수 있는 환경이라면 CLI로 먼저 시작하세요. 원격 연결을 제공하는 클라이언트에서는 MCP를 사용할 수 있습니다.

MCP URL

https://api.joripspace.com/mcp

CLI

codex mcp add joripspace --url https://api.joripspace.com/mcp
codex mcp login joripspace

CLI

claude mcp add --transport http joripspace --scope user https://api.joripspace.com/mcp

Claude Code에서는 /mcp를 열어 조립스페이스에 로그인하세요. 다른 클라이언트는 서버 URL을 등록한 뒤 OAuth 또는 로그인 메뉴를 사용합니다. 서버를 등록하고 브라우저 승인까지 마치면 계정에 연결됩니다. CLI를 사용하고 있더라도 MCP 클라이언트에서는 별도로 로그인해야 합니다.

인증과 프로젝트 세션

로그인을 마쳤다면 에이전트에게 프로젝트 연결을 요청해 보세요. start_project_session에 프로젝트 이름을 전달하면 현재 상태를 확인할 수 있습니다. 아래 JSON-RPC 예제는 이 도구를 호출하는 요청입니다.

연결 코드를 사용하는 클라이언트라면 MCP 연결을 먼저 초기화하고 반환된 Mcp-Session-Id를 유지합니다. 5분 일회용 코드로 exchange_connection_code를 호출한 뒤 같은 세션에서 start_project_session을 실행하세요. 인증정보는 서버에서 관리하므로 응답에 API 토큰이 포함되지 않습니다.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "start_project_session",
    "arguments": {
      "project_id": "PROJECT"
    }
  }
}

응답에는 프로젝트 선택과 작업 폴더 준비에 필요한 안내가 담깁니다. 에이전트는 기존 프로젝트 지침을 유지하면서 작업을 이어갈 수 있습니다. 나중에 CLI로 전환하려면 저장된 CLI 로그인을 사용하거나 joripspace login으로 연결하세요. MCP 클라이언트에서 인증정보를 복사할 필요는 없습니다.

필요한 도구와 안내 찾기

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

tools/list로 사용 가능한 도구를 볼 수 있습니다. 각 도구의 inputSchema에는 어떤 정보를 입력해야 하는지 설명되어 있습니다. 에이전트는 search_knowledge로 작업에 맞는 안내를 검색하고, resources/list에서 매뉴얼을 찾아 resources/read로 읽을 수도 있습니다.

예를 들어 manual://mcp/tools는 도구 사용법을, manual://debug/operations는 운영 점검 방법을 안내합니다. 이 리소스는 브라우저 대신 MCP 클라이언트에서 열어 보세요. 필요한 안내를 그때 찾아 읽을 수 있어 모든 도구 옵션을 AGENTS.md에 옮겨 적을 필요가 없습니다.

도구 참조

아래 도구를 펼치면 필요한 입력 항목과 권한, 관련 CLI 명령을 확인할 수 있습니다. 목록은 서버의 도구 정의에 맞춰 갱신됩니다. 현재 연결에서 사용할 수 있는 도구와 입력 항목은 MCP 클라이언트에서도 확인할 수 있습니다. 로그인을 마친 연결에서는 도구를 호출할 때마다 API 토큰을 입력할 필요가 없습니다.

get_current_api_token

CLI: joripspace tokens current

인증: 계정 로그인

API: GET /v1/me/tokens/current

추가로 입력할 항목이 없습니다.

revoke_api_token

CLI: joripspace tokens revoke

인증: 계정 로그인

API: DELETE /v1/me/tokens/{token_id}

입력 항목	자료형	필수 여부
`token_id`	`string`	예

get_realtime_v2

CLI: joripspace realtime-v2 status

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/realtime-v2

입력 항목	자료형	필수 여부
`project_id`	`string`	예

manage_realtime_v2

CLI: joripspace realtime-v2 activate

인증: 프로젝트 접근 권한 · project.secrets.generate

API: POST /v1/projects/{project_id}/realtime-v2/activate

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`action`	`string · activate / rotate / disable / revoke-key`	예
`kid`	`string`	아니요

start_login

CLI: joripspace login

인증: 로그인 없이 사용

API: GET https://joripspace.com/connect/

추가로 입력할 항목이 없습니다.

browser_connect

CLI: joripspace login

인증: 로그인 없이 사용

API: GET https://joripspace.com/connect/

추가로 입력할 항목이 없습니다.

exchange_connection_code

CLI: joripspace login

인증: 로그인 없이 사용

API: POST /v1/auth/connection-code/exchange

입력 항목	자료형	필수 여부
`code`	`string`	예

search_knowledge

CLI: joripspace knowledge search

인증: 로그인 없이 사용

API: GET /v1/knowledge/search

입력 항목	자료형	필수 여부
`query`	`string`	예
`limit`	`number`	아니요

start_project_session

CLI: joripspace start

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/me/projects

입력 항목	자료형	필수 여부
`project_id`	`string`	아니요

get_session_context

CLI: joripspace me

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/me/projects

추가로 입력할 항목이 없습니다.

list_my_projects

CLI: joripspace projects

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/me/projects

추가로 입력할 항목이 없습니다.

select_project

CLI: joripspace link

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예

list_templates

CLI: joripspace template list

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/templates

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`cursor`	`string`	아니요

prepare_project_workspace

CLI: joripspace link

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예

deploy_code

CLI: joripspace deploy

인증: 프로젝트 접근 권한 · project.deploy

API: POST /v1/projects/{project_id}/deploy

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`label`	`string`	예
`entrypoint`	`string`	예
`files`	`object`	예
`deployment_verification`	`object`	예

get_project

CLI: joripspace get

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예

create_project

CLI: joripspace create

인증: 계정 로그인

API: POST /v1/projects

입력 항목	자료형	필수 여부
`name`	`string`	예
`plan`	`string · free`	아니요
`confirmed`	`boolean`	아니요
`free_project_noncommercial_agreement`	`boolean`	아니요
`billing_agreement`	`boolean`	아니요
`free_project_retention_agreement`	`boolean`	아니요

prepare_github_workflow

CLI: joripspace github prepare

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`entrypoint`	`string`	예
`package_build`	`boolean`	아니요

describe_db

CLI: joripspace db schema

인증: 프로젝트 접근 권한 · project.db.read

API: GET /v1/projects/{project_id}/db/schema

입력 항목	자료형	필수 여부
`project_id`	`string`	예

query_db

CLI: joripspace db query

인증: 프로젝트 접근 권한 · project.db.read

API: POST /v1/projects/{project_id}/db/query

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`sql`	`string`	예

run_db_migration

CLI: joripspace db migrate

인증: 프로젝트 접근 권한 · project.db.write

API: POST /v1/projects/{project_id}/db/migrations

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`name`	`string`	아니요
`sql`	`string`	예

list_storage_objects

CLI: joripspace storage list

인증: 프로젝트 접근 권한 · project.storage.read

API: GET /v1/projects/{project_id}/storage/objects

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`prefix`	`string`	아니요
`cursor`	`string`	아니요
`limit`	`number`	아니요

read_storage_object

CLI: joripspace storage get

인증: 프로젝트 접근 권한 · project.storage.read

API: GET /v1/projects/{project_id}/storage/objects/{key}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`key`	`string`	예

write_storage_object

CLI: joripspace storage put

인증: 프로젝트 접근 권한 · project.storage.write

API: PUT /v1/projects/{project_id}/storage/objects/{key}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`key`	`string`	예
`text`	`string`	아니요
`base64`	`string`	아니요
`content_type`	`string`	아니요

delete_storage_object

CLI: joripspace storage delete

인증: 프로젝트 접근 권한 · project.storage.write

API: DELETE /v1/projects/{project_id}/storage/objects/{key}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`key`	`string`	예

list_deployments

CLI: joripspace deployments

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/deployments

입력 항목	자료형	필수 여부
`include_failure_details`	`boolean`	아니요
`project_id`	`string`	예
`limit`	`number`	아니요

get_deployment_source

CLI: joripspace deployment pull

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/deployments/{deployment_id}/source

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`deployment_id`	`string`	예

rollback_deployment

CLI: joripspace rollback

인증: 프로젝트 접근 권한 · project.rollback

API: POST /v1/projects/{project_id}/deployments/{deployment_id}/rollback

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`deployment_id`	`string`	예

create_checkpoint

CLI: joripspace checkpoint save

인증: 프로젝트 접근 권한 · project.checkpoint.write

API: POST /v1/projects/{project_id}/checkpoint-uploads

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`label`	`string`	예
`source_type`	`string · manual / agent / restore_safety`	아니요
`idempotency_key`	`string`	아니요

list_checkpoints

CLI: joripspace checkpoint list

인증: 프로젝트 접근 권한 · project.checkpoint.read

API: GET /v1/projects/{project_id}/checkpoints

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`limit`	`number`	아니요
`cursor`	`string`	아니요

get_checkpoint

CLI: joripspace checkpoint get

인증: 프로젝트 접근 권한 · project.checkpoint.read

API: GET /v1/projects/{project_id}/checkpoints/{checkpoint_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`checkpoint_id`	`string`	예

restore_checkpoint

CLI: joripspace checkpoint restore

인증: 프로젝트 접근 권한 · project.checkpoint.read

API: GET /v1/projects/{project_id}/checkpoints/{checkpoint_id}/restore-plan

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`checkpoint_id`	`string`	예

deploy_checkpoint

CLI: joripspace checkpoint deploy

인증: 프로젝트 접근 권한 · project.checkpoint.deploy

API: POST /v1/projects/{project_id}/checkpoints/{checkpoint_id}/deploy

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`checkpoint_id`	`string`	예
`deployment_verification`	`object`	예

update_checkpoint

CLI: joripspace checkpoint update

인증: 프로젝트 접근 권한 · project.checkpoint.write

API: PATCH /v1/projects/{project_id}/checkpoints/{checkpoint_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`checkpoint_id`	`string`	예
`label`	`string,null`	아니요
`pinned`	`boolean`	아니요

delete_checkpoint

CLI: joripspace checkpoint delete

인증: 프로젝트 접근 권한 · project.checkpoint.delete

API: DELETE /v1/projects/{project_id}/checkpoints/{checkpoint_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`checkpoint_id`	`string`	예

generate_project_secret

CLI: joripspace secret generate

인증: 프로젝트 접근 권한 · project.secrets.generate

API: POST /v1/projects/{project_id}/secrets/generate

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`name`	`string`	예

get_usage_summary

CLI: joripspace usage-summary

인증: 프로젝트 접근 권한 · usage.read

API: GET /v1/projects/{project_id}/usage/summary

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`from`	`string`	아니요
`to`	`string`	아니요

get_usage_breakdown

CLI: joripspace usage-breakdown

인증: 프로젝트 접근 권한 · usage.read

API: GET /v1/projects/{project_id}/usage/breakdown

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`from`	`string`	아니요
`to`	`string`	아니요
`group_by`	`string · hour / day`	아니요

list_secrets

CLI: joripspace secret list

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/secrets

입력 항목	자료형	필수 여부
`project_id`	`string`	예

list_runtime_events

CLI: joripspace events

인증: 프로젝트 접근 권한 · logs.read

API: GET /v1/projects/{project_id}/runtime-events

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`event_type`	`string · request / error`	아니요
`limit`	`number`	아니요

list_crons

CLI: joripspace crons

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/crons

입력 항목	자료형	필수 여부
`project_id`	`string`	예

create_cron

CLI: joripspace cron create

인증: 프로젝트 접근 권한 · project.crons.write

API: POST /v1/projects/{project_id}/crons

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`name`	`string`	아니요
`schedule`	`string`	예
`method`	`string · GET / POST`	아니요
`path`	`string`	예

run_cron

CLI: joripspace cron run

인증: 프로젝트 접근 권한 · project.crons.write

API: POST /v1/projects/{project_id}/crons/{cron_id}/run

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`cron_id`	`string`	예

delete_cron

CLI: joripspace cron delete

인증: 프로젝트 접근 권한 · project.crons.write

API: DELETE /v1/projects/{project_id}/crons/{cron_id}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`cron_id`	`string`	예

list_domains

CLI: joripspace domains

인증: 프로젝트 접근 권한 · project.read

API: GET /v1/projects/{project_id}/domains

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`cursor`	`string`	아니요
`limit`	`number`	아니요

create_domain

CLI: joripspace domain create

인증: 프로젝트 접근 권한 · project.domains.write

API: POST /v1/projects/{project_id}/domains

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`hostname`	`string`	예

verify_domain

CLI: joripspace domain verify

인증: 프로젝트 접근 권한 · project.domains.write

API: POST /v1/projects/{project_id}/domains/{hostname}/verify

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`hostname`	`string`	예

delete_domain

CLI: joripspace domain delete

인증: 프로젝트 접근 권한 · project.domains.write

API: DELETE /v1/projects/{project_id}/domains/{hostname}

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`hostname`	`string`	예

connect_mail

CLI: joripspace mail connect

인증: 프로젝트 접근 권한 · project.mail.read

API: GET /v1/projects/{project_id}/mail/status

입력 항목	자료형	필수 여부
`project_id`	`string`	예

get_mail_status

CLI: joripspace mail status

인증: 프로젝트 접근 권한 · project.mail.read

API: GET /v1/projects/{project_id}/mail/status

입력 항목	자료형	필수 여부
`project_id`	`string`	예

send_test_mail

CLI: joripspace mail test

인증: 프로젝트 접근 권한 · project.mail.send

API: POST /v1/projects/{project_id}/mail/test

입력 항목	자료형	필수 여부
`project_id`	`string`	예
`to`	`string`	아니요
`subject`	`string`	아니요

프로젝트 권한과 연결 토큰

MCP 도구는 로그인한 계정의 프로젝트 권한으로 동작합니다. 프로젝트를 사용할 수 없다면 해당 계정의 접근 권한을 확인해 보세요. MCP에서는 비밀값을 표시하지 않고 Secret을 생성하거나 이름을 조회할 수 있습니다. 외부 서비스에서 발급한 키를 등록·교체하려면 CLI의 secret set --value-stdin 또는 프로젝트 비밀 키 화면을 사용하세요. 문제 신고나 개선 제안은 CLI의 report로 보낼 수 있습니다.

JSON-RPC

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "revoke_api_token",
    "arguments": {
      "token_id": "current"
    }
  }
}

위 예제는 현재 연결에 사용된 토큰을 폐기합니다. 토큰이 노출되는 등 연결을 사용 중지해야 할 때 실행하세요. 먼저 get_current_api_token으로 ID를 확인할 수 있습니다. 같은 계정의 다른 토큰을 폐기하려면 revoke_api_token에 current 대신 해당 토큰의 정확한 ID를 넣습니다.

현재 토큰을 폐기하면 연결이 끊기므로 새 코드로 다시 연결해야 합니다. 토큰 값은 대화·신고 내용·로그에 남기지 않도록 주의해 주세요.

문서 전체 보기 프로젝트 열기